Before: You wrote the code, you owned the consequences.

Now: AI writes the code, you still own the consequences.

Agents have changed the writing part. You're still the one accountable for it. You are the one who has to explain it or defend it. Unlost keeps that context close to you.

I built Unlost because something was slipping away from me with coding agents. Unlost tries to keep some adherence between the agent's authorship and my owership as an engineer.

A colleague asks why it's built this way. You know it works. You're less sure you can explain it. The reasoning was in the chat. unlost trace or unlost brief give you the answer, not from memory, from the record.

Six months later, someone needs to change it. Maybe it's you. The agent doesn't remember. The chat is gone. The commit message says "feat: add retry logic." unlost trace gives you the decision chain. unlost challenge tells you whether the original call still holds before you undo it.

Production is down. You're reading code under pressure that you didn't write. You don't know if the retry logic was intentional or a guess. unlost trace reconstructs the chain. unlost brief tells you what bites.

The PR is the handoff. To your team, and to your future self. The diff shows what changed. It doesn't show what was tried and rejected, what constraint you were navigating, what's still open. unlost pr-comment posts that note from session memory, not the diff. Ownership transfers with the code.

curl -fsSL https://unlost.unfault.dev/install.sh | bash

Or download the binary manually from releases.

Claude Code (Global, zero per-repo config):

unlost config agent claude --global

OpenCode (Global):

unlost config agent opencode --global

Or per-project: unlost config agent opencode --path .

GitHub Copilot CLI (Per-project):

unlost config agent copilot --path .

This writes .github/hooks/unlost.json and installs a Copilot skill at .github/copilot/skills/unlost/.

By default, unlost uses whatever LLM your agent is configured with. You can override this for better results (e.g., using a smaller/faster model for extraction):

# Use Claude
unlost config llm anthropic --model claude-3-5-sonnet-20241022

# Or OpenAI
unlost config llm openai --model gpt-4o-mini

# Staff engineer's debrief on any file or module
unlost brief
unlost brief src/governor.rs

# What happened recently in this file?
unlost recall src/http_proxy.rs

# Reconstruct the decision chain that led to the current state
unlost trace src/governor.rs
unlost trace "why is the connection timeout 30 seconds?"

• unlost brief: Scans all recorded memory and git commits. Scores by importance, not recency. Answers: what is this, what are the non-obvious choices, where do I start.
• unlost trace: Builds a chronological causal chain seeded by semantic similarity. Answers: why is the code the way it is, not just what happened recently.
• unlost recall: Narrates the recent story for a file or concept. Useful for catching up after time away.

# Argue with a past decision before you reverse it
unlost challenge "was using fastembed the right call?"

# Think through options using what this repo already knows
unlost explore "should we keep lancedb or move to sqlite+fts?"

• unlost challenge: Surfaces recorded rationale, failure modes, and alternatives. Gives you a verdict grounded in history before you make a call.
• unlost explore: Forward-looking planning. Labels what comes from memory [memory] vs. external knowledge [outside] so you know what you're actually standing on.

# How did you and the agent collaborate? What should change?
unlost reflect
unlost reflect --mode tune
unlost reflect --mode both --since 7d

• unlost reflect: Reads per-turn evaluation telemetry collected silently during sessions and generates a structured narrative via LLM — no raw transcript required. Three modes: coach (your collaboration habits), tune (agent drift, loops, hallucination), both. Every output opens with a scannable NEXT ACTIONS block. The tune and both modes include a SKILL ASSESSMENT that audits your installed agent skills against observed turn data and suggests behavioural gaps to fill.

# Post a PR comment from session history: intent, tradeoffs, risks
unlost pr-comment 42
unlost pr-comment https://github.com/owner/repo/pull/42

• unlost pr-comment: Posts a "staff engineer" style note on the PR. Not a diff summary. A note from someone who was in the room: what changed functionally, what we were navigating, what's left open, what to re-read in three months.

The /unlost-walkthrough agent skill does the same thing interactively: step through what changed, in order, with reasons, so you can review with confidence rather than just approve.

1. Capture: After each agent exchange → extracts a structured capsule (intent, decision, rationale, symbols) plus a TurnEval — per-turn coaching and agent-tuning scores computed locally with zero LLM calls.
2. Store: Capsules stay local, embedded with fastembed, indexed in LanceDB. Nothing leaves your machine.
3. Guide: Before each prompt → checks for friction (loops, drift, misalignment). Injects a correction if something is off.
4. Recall: Capsules are queryable anytime, by file, symbol, question, or concept.
5. Reflect: unlost reflect reads the TurnEval timeline and generates a structured coaching/diagnostics narrative — developer habits, agent patterns, skill gaps — without touching raw transcript text.

Everything unlost stores stays on your machine:

• Capsules — Stored locally in ~/.local/share/unlost/workspaces/
• Embeddings — Generated locally with fastembed
• Query history — Never leaves your disk

The only network call unlost makes is to the LLM provider you configure for extraction. That LLM sees only the exchange text (no tool outputs), and it produces a capsule that never goes back upstream.

cargo test
cargo build

MIT. See LICENSE for details.

• agents/README.md - Agent integrations