Keep your agents from going off track

Unlost intercepts before your agents drift. It spots friction, injects guidance, and records what actually happened.

Privacy First

Capsules and indexes stay on your machine.

Open-Source

Built in the open under a MIT license.

Non-Blocking

Journaling returns immediately; heavy work runs async.

Coming soon

The Babysitting Tax

Drift

The Apology Loop

"I'm sorry, you're right. Let me fix that." [Proceeds to break the exact same thing for the 4th time]

Re-discovery

Context Gaslighting

The agent is convinced it fixed the bug. The terminal is a sea of red. The agent tells you you're wrong.

False Progress

The $50 Side-Quest

You asked for a CSS tweak; you come back 10 minutes later and it's refactoring your entire auth flow for no reason.

Install

Get Unlost

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

For Windows, please download the binary from our releases page.

Agent Integration

Hook unlost into your agent. Choose global for system-wide coverage, or per-project for opt-in control.

# Claude Code - one command, works everywhere
unlost config agent claudecode --global

# OpenCode - opt-in per repository
cd your-project
unlost config agent opencode --path .

If you want to use Unlost with your favourite agent, please drop us a note.

Configure Your LLM

Unlost requires an LLM for capsule extraction and summarization. While friction detection works locally, a dedicated extraction model dramatically improves capsule quality. Better structured data means more accurate recall and sharper pattern detection.

unlost config llm anthropic --model claude-sonnet-4-5-20250929
unlost config llm openai --model gpt-4o-mini

Recommendation: Use a fast, cheap model like GPT-4o-mini or Claude 3.5 Haiku. Extraction doesn't need reasoning; just structured output. You'll process thousands of messages; speed and cost matter more than intelligence.

That's it. Next time you start your agent, unlost will automatically work alongside it. Happy coding!

Commands

unlost recall

Memory

Recall the story so far (proactive overview) from a specific file or directory.

unlost recall src/http_proxy.rs
unlost recall src/ --depth 5

unlost query

Memory

Semantic search across recorded capsules with natural language.

unlost query "why did we rename the capsules table?"
unlost query --symbol proxy_request
unlost query "auth flow changes" --since 7d

unlost metrics

Monitor

Show workspace metrics (local, derived from metrics.jsonl).

unlost metrics

unlost inspect

Monitor

Inspect stored capsules for this workspace.

unlost inspect

unlost reindex

Manage

Rebuild LanceDB index from capsules.jsonl.

unlost reindex

unlost clear

Manage

Delete all generated data for the current workspace.

unlost clear

unlost where

Manage

Show where the workspace's files are stored.

unlost where

unlost config

Manage

Manage configuration (LLM provider, agent integrations, etc.).

unlost config
unlost config agent claudecode --global
unlost config agent opencode --path .
unlost config llm anthropic --model claude-3-5-sonnet-20241022

How It Works

01

Intercept & Record

Hooks into agent events and writes everything to an append-only JSONL journal. Non-blocking; returns immediately while processing continues in the background.

# Journal entry

{timestamp: "2025-02-09T14:23:00Z", event: "message", role: "assistant", content: "..."}

02

Summarize & Store

LLM extracts structured capsules (intent, decision, rationale, next_steps). FastEmbed generates local embeddings. Everything stored in LanceDB; no data leaves your machine.

# Capsule + embedding

{intent: "Fix auth", decision: "Use middleware", rationale: "...", embedding: [0.23, -0.45, ...]}

03

Friction & Failure Mode Detection

Analyzes conversation patterns in real-time: drift, retry spirals, false progress, unbounded horizons. Detects when the agent is about to go off the rails.

# Friction detected

retry spiral after 3 failed attempts

pattern: "The Apology Loop" | confidence: 0.87

04

Injection Decision

Automatic intervention when friction is detected. Injects contextual guidance into the conversation before the agent sends its next prompt. No manual intervention.

# System message injected

[SYSTEM: You've attempted this fix 3 times. Consider a different approach.]

05

Recall & Query

Async semantic search across your workspace memory. Query by natural language, symbols, or file paths. Returns relevant capsules with context; why did we do X?

# User query

$ unlost query "why did we switch to postgres?"

# Result

→ Found: 3 capsules | Intent: "Improve analytics performance"

Who's behind this?

I built Unlost because I keep coming back to codebases (including my own) and spending the first hour rebuilding context. Agents make that worse when they drift and I usually got upset with them. Unlost is my attempt at keeping the joy alive.

If something feels rough, open an issue. I read them. github.com/unfault/unlost/issues

- Sylvain