<h2 align="center">
<br>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/unfault/unlost/main/public/logo.png">
<img alt="Unfault" src="https://raw.githubusercontent.com/unfault/unlost/main/public/logo.png" >
</picture>
</h2>
<h4 align="center">Unlost - Agent orientation that prevents the babysitting tax</h4>
---
## Mission
Keep your agents oriented.
You know the drill:
- You ask an agent to rename a function. It renames it, then renames it again. Then again. You finally intervene: "stop renaming, just add a wrapper."
- An agent spent forty minutes "implementing" a feature. Turns out it only modified the README.
- You come back after the weekend. The agent made decisions you don't understand. Nobody remembers why.
- An agent says it finished. It didn't. It created a file that was never committed.
That's the babysitting tax. It adds up fast.
Unlost intercepts before you pay. It detects these failure modes and guides agents back on track:
| **Drift** | Agent thinks the system works one way. The code says otherwise. | Surfaces the contradiction before the agent compounds the error. |
| **Rediscovery** | You explain the same thing you explained last week. | Reminds the agent of what was already decided. |
| **Decision Conflict** | Agent starts implementing something that contradicts a project decision. | Flags the conflict and reminds the agent of the constraint. |
| **Retry Spiral** | Agent tries the same failed approach. Again. And again. | Catches the loop before another hour burns. |
| **False Progress** | Agent claims done. Verification would fail. | Detects the claim and flags it for review. |
| **Unbounded Horizon** | Agent wanders into unrelated side-quests. | Nudges back toward the original goal. |
## Use unlost with your favourite agent
### Claude
All your Claude Code projects, forever, with zero per-repo config:
```bash
unlost config agent claude --global
```
That's it. Unlost hooks into every Claude Code session, checks for friction before each prompt, injects guidance when something feels off, and quietly records what actually happened (intent, decision, rationale, next steps) into local capsules you can query anytime.
### OpenCode
All your OpenCode projects (global config):
```bash
unlost config agent opencode --global
```
Or one project at a time:
```bash
unlost config agent opencode --path .
```
Same deal. Unlost spots drift, catches false progress, and builds a local trail of decisions — without storing full transcripts.
## How it works
```
1. Your agent is about to send a prompt → unlost checks for friction
2. If something feels off → injects guidance before the agent goes off-track
3. After each exchange → extract a capsule (what we tried, why, next steps)
4. Capsules stay local → query anytime: "why did we do X?"
```
No transcripts. No external storage. Just small, queryable capsules that remember what your agents decided and why.
## Configure your LLM (optional, for better capsules)
Unlost uses a small LLM to extract structured capsules from agent exchanges. By default, it uses whatever LLM your agent is already configured with. You can override this for better results:
```bash
# Use Claude for extraction
unlost config llm anthropic --model claude-sonnet-4-5-20250929
# Or OpenAI
unlost config llm openai --model gpt-4o-mini
```
**What the LLM is fed:**
- The raw user → assistant exchange (just the text, not tool outputs)
- Recent capsule history from the workspace (to detect contradictions)
**What it produces:**
- A structured capsule with: category, intent, decision, rationale, next_steps, symbols, failure_mode
**Where it runs:**
- The LLM call goes through your configured provider (Anthropic, OpenAI, etc.)
- Capsule storage is entirely local — embeddings, the capsules themselves, and query history never leave your machine
## Recall & Query
Your agents built a memory trail. Here's how to query it:
```bash
# What did we decide here?
unlost recall src/http_proxy.rs
# Why did we rename the capsules table?
unlost query "why did we rename the capsules table?"
# Find everything about the proxy routing
unlost query --symbol proxy_request
```
## The Cognitive Mirror (Metrics)
Unlost doesn't just store memory; it tracks the **trajectory** of your collaboration. As context grows, agents often begin to stall or drift. Unlost monitors these patterns across three "Basins of Friction":
| **Loop** | Repetitive stalls | Symbol repetition, novelty collapse, logic churn. |
| **Spec** | Alignment debt | VERBATIM instruction repeats, corrective keywords. |
| **Drift** | Grounding failure | Hallucinated paths, ignoring user-mentioned files. |
Use the `metrics` command to see the "Cognitive Mirror" of your workspace:
```bash
unlost metrics
```
This reveals:
- **Friction vs Context Size**: See how the warning rate spikes as your input tokens grow (the "Lost in Context" threshold).
- **Average Verbosity**: Measures "Fluency" — how much the assistant is dominating the token share (a leading indicator for over-trust and blind acceptance).
- **Average Interval**: How many tokens of productive work you get between trajectory breakdowns.
- **Top Friction Files**: Codebase "hotspots" that are consistently causing the agent to stall or drift.
## Replay & Grounding
Did an agent session happen while Unlost was off? Or do you want to analyze a past transcript?
```bash
# Replay OpenCode sessions from your current repo
unlost replay opencode --git-grounding
# Replay a Claude transcript file
unlost replay claude --transcript-path history.json --git-grounding
```
The `--git-grounding` flag verifies agent claims against actual commits in your history, marking capsules as "Verified via Git" when a match is found.
## Install
```bash
Or download the binary manually from [releases](https://github.com/unfault/unlost/releases).
## Dev
```bash
cargo test
cargo build
```
## Privacy First
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.
## License
MIT. See [LICENSE](LICENSE) for details.
## Docs
- `agents/README.md` - Agent integrations