limbo-code 0.2.1__tar.gz → 0.3__tar.gz

{limbo_code-0.2.1 → limbo_code-0.3}/AGENTS.md

@@ -2,7 +2,7 @@
 
 **Limbo** is a minimal terminal AI coding agent (Python 3.11+, Textual). Users converse with an LLM in a TUI to explore, read, edit, and write code via 7 tools. A `--headless` flag runs a plain-terminal REPL frontend instead of the TUI (Herdr/script control, RFC LIM-60).
 
-**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter).
+**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter). `ToolRegistry` runs a `before_tool`/`after_tool` hook chain (`admit()` then `run()`; the agent journals a call's intent only after `admit()` lets it through) (`tools/hooks.py`: `Block` / `Rewrite` / replace result; a raising hook blocks) that is empty by default; the only built-in hook is `/plan` (read-only plan mode: replay-safe tools and read-only bash only, also enforced on Code Mode sub-calls, persisted as `SessionMeta.plan_mode`).
 
 ## Quick Start
 
@@ -37,10 +37,19 @@ src/limbo/
 ├── headless.py       # --headless frontend (RFC LIM-60): line-oriented REPL on the
 │                     # primary screen for Herdr (agent prompt/send-keys/read/wait);
 │                     # same TurnPump seam as the TUI, no textual import
-├── sessions.py       # Session JSONL save/load/list/export
+├── conversation.py   # Conversation: the live agent+pump pair both frontends drive —
+│                     # new/switch/fork/handoff (load before close), lifecycle reporting
+│                     # (drive), /goal verify-proposal flow
+├── sessions.py       # Session JSONL file format: records, save/load/list/export
+├── journal.py        # SessionJournal: when/in what order records reach the file
+│                     # (watermark, rewrite fallback, queue re-journal, meta patches)
 ├── trace.py          # Append-only JSONL run log (sessions/traces/)
+├── tracing/          # /tracing-viewer: loopback web viewer over trace files (stdlib
+│                     # http.server; index.py offsets, model.py tree, static/index.html)
 ├── integrations/     # External mux/orchestrator lifecycle reporters: base.py (protocol
-│                     # + CompositeReporter + AgentState), herdr.py; create_reporters() fans out
+│                     # + CompositeReporter + AgentState + TurnOutcome), herdr.py,
+│                     # osc7501.py (terminal program status; TTY only, LIMBO_PROGRAM_STATUS=0
+│                     # opts out, tmux passthrough); create_reporters() fans out
 ├── skills.py         # SKILL.md discovery (user + project dirs)
 ├── llm/              # catalog.py (provider/model specs), factory.py (dialect→client),
 │                     # openai_client.py, anthropic_client.py, responses_client.py, retry.py, sse.py,
@@ -48,7 +57,7 @@ src/limbo/
 │                     # scaffold.py (plumbing shared by dialect clients: credentials, retry, images)
 ├── tools/            # base.py (BaseTool + path resolution + truncation), registry.py (dispatch;
 │                     # code_mode flag filters definitions() to [run_code], all_definitions() feeds
-│                     # the SDK), mutation_queue.py (per-file locks), ignore.py (.gitignore),
+│                     # the SDK), hooks.py (before/after tool hook chain + plan mode), mutation_queue.py (per-file locks), ignore.py (.gitignore),
 │                     # read/bash/edit/write/grep/find/ls/run_code.py (the Code Mode transport)
 └── ui/               # app.py + app.tcss (ALL styles here; theme vars only, no bare hex),
                       # theme.py (limbo-dark/-light, RFC LIM-16), commands.py (slash registry
@@ -62,12 +71,13 @@ src/limbo/
 ## Agent Loop
 
 - `Agent.run()` yields `AgentEvent`: `TextDelta`, `ThinkingDelta`, `ToolCallRequest`, `ToolResultEvent`, `ErrorEvent`, `CompactionEvent`, `UsageUpdate`, `SteerEvent`
-- Loop top: auto-compaction check → steer drain → LLM call. Turn ends on a tool-call-free response; `max_iterations` (default 50) cancels pending calls with placeholder results
+- Loop top: auto-compaction check → steer drain → LLM call. A provider context-overflow error (`llm.retry.is_context_overflow`: 413 or known overflow texts, never rate limits) triggers `compact(trigger="overflow")` and one resend per turn; a second overflow or a failed compaction surfaces as `ErrorEvent`. Turn ends on a tool-call-free response; `max_iterations` (default 50) cancels pending calls with placeholder results
 - Tool calls in one turn run **concurrently** (`[tools] parallel`); results stream in completion order, recorded in source order; same-file mutations serialized by `mutation_queue`
 - `finish_reason` `length`/`max_tokens` → whole batch failed without execution; the error result names the effective `max_tokens` and steers the model to write large scripts via `write` instead of re-issuing the same call. 3 consecutive length stops abort the turn with actionable guidance (trace `kind=length_stop_loop`); a text-only truncated response emits a "may be incomplete" warning
-- Mid-turn user input queues as *steer* (LIM-20): injected at loop top, or as turn-end follow-up
+- Mid-turn user input queues as *steer* (LIM-20): injected at loop top, or as turn-end follow-up. Alt+Enter (headless: `/queue <text>`) queues a `follow_up` instead: only `TurnPump._supervise` drains it, after the whole task (goal loop included). Every queue change is journaled in the session file (`queue` records: `queued` immediately, `dequeued` after the message carrying it is saved), so queued messages survive a crash and are restored (and re-rendered) on resume
 - Reasoning is stored on assistant messages and replayed per dialect (Anthropic thinking signatures, Kimi `reasoning_content`, Responses encrypted items)
-- Usage counters normalize in `llm/usage.py` (`input_tokens`+`cache_read`, `prompt_tokens`, DeepSeek cache hits) and feed the compaction trigger via `PromptSizeEstimator`
+- A retryable failure after the stream started (dropped connection, 5xx, overload) resends the same request up to `max_retries` times (`RetryEvent`; the partial response is discarded and the TUI strikes it through); failures before the first event are retried inside the client (`llm/retry.py`)
+- Usage counters normalize in `llm/usage.py` (`input_tokens`+`cache_read`, `prompt_tokens`, DeepSeek cache hits) and feed the compaction trigger via `PromptSizeEstimator`; every billed call (turns, compaction summaries, `/btw`) is added to the per-`provider/model` ledger `SessionMeta.usage`, so the token counter survives resume. The Responses client sends `prompt_cache_key = session id`
 
 ## LLM & Config
 
@@ -79,17 +89,19 @@ Providers/models live in `llm/catalog.py`; unknown models get generic OpenAI-com
 [tools]      # bash_enabled = true, parallel = true
 [compaction] # enabled, reserve_tokens = 16384, keep_recent_tokens = 20000
 [goal]       # max_rounds = 10, verify_timeout_ms = 600000
+[queue]      # after_failed_run = "continue" | "keep" | "withdraw" (queued
+             # messages after an LLM-error turn; keep/withdraw end the task)
 [ui]         # theme, show_banner
 [providers.<id>]  # base_url / api_key / api_key_env / headers
 ```
 
-`/model` rebuilds the client mid-session (refused while busy) and persists via tomlkit. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls. Trace events: `session_start`, `user_message`, `llm_request` (full body), `llm_response`, `tool_call`, `tool_result`, `compaction*`, `error`, `turn_end`. `/export [path]` merges meta + trace + message snapshot (Markdown if `.md`).
+`/model` rebuilds the client mid-session (refused while busy) and persists via tomlkit. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls: each call commits a `tool_intent` record before it runs, so a crashed call is re-run on the next turn if its tool is `replay = "safe"` (read/grep/find/ls), otherwise marked "may have partially run" (intent committed) or "did not run" (no intent); legacy sessions without `meta.tool_intents` get the generic placeholder. Trace events: `session_start`, `user_message`, `llm_request` (full body), `llm_response`, `tool_call`, `tool_result`, `tool_recovery`, `compaction*`, `error`, `turn_end`. `/export [path]` merges meta + trace + message snapshot (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new self-contained session, `/handoff <note>` starts a clean linked session from a note; both record `parent_session`/`fork_at` and leave the parent untouched. Code Mode sub-calls are traced as `tool_call`/`tool_result` with `parent_call_id`. `limbo --json` (implies `--headless`) prints every event as one JSON object per line.
 
 Skills: `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<name>/SKILL.md` (project, wins collisions) — injected as a `<available_skills>` catalog in the system prompt and invocable via `/<name> [args]`.
 
 ## UI
 
-Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs + ⌨code badge while Code Mode is on) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /export /compact /model /code-mode /help /2048 /goal` + skill commands. '/'-leading input that matches no command but looks like a path is sent as a normal message with existing files auto-attached (`ui/path_input.py`); a leading space forces plain text. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
+Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs + ⌨code badge while Code Mode is on) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, Alt+Enter queues a follow-up while busy (`ui/key_fixes.py` maps its modifyOtherKeys/kitty/ESC forms), paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /fork /handoff /export /tracing-viewer /compact /model /code-mode /plan /help /2048 /goal` + skill commands. '/'-leading input that matches no command but looks like a path is sent as a normal message with existing files auto-attached (`ui/path_input.py`); a leading space forces plain text. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
 
 `/goal <text>` starts closed-loop mode (LIM-40): the first round is a proposal round — the model explores the repo and proposes acceptance command(s) in a `<verify_proposal>` block; the user confirms in a picker (accept / edit / skip), then the goal branch of the `TurnPump` (non-UI, shared by any frontend) runs each round as a complete `Agent.run()` turn and executes the verify command; exit 0 ends the loop, otherwise the failure output is fed back verbatim into the next round until `max_rounds`, when a no-tool wrap-up turn summarizes and any user message resumes with a fresh budget. Goal state persists on `SessionMeta.goal`. Esc during verify cancels the subprocess.
 
@@ -103,7 +115,7 @@ Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow
   history — sub-calls never do. `SessionMeta.code_mode` persists the mode
   across resume
 - System prompt = hardcoded tool guidelines + `<workdir>/AGENTS.md` & `~/.limbo/AGENTS.md` (XML-wrapped) + skills catalog. **This file is injected into every request — keep it accurate and lean.**
-- Session files fully rewritten per save (atomic, 0600); trace holds full-fidelity record
+- Session JSONL is checkpointed mid-turn (before/after each LLM request, after each tool batch): new messages are appended; full atomic rewrite (0600) only on first save, after a failed append, or when resume repaired dangling calls. Meta changes append `meta_patch` (a title change rewrites just the meta line via `rewrite_meta_line`, which keeps every other record). Compaction is non-destructive: a `compaction` record is appended, summarized messages stay in the file, and loading selects the active range from the latest record's `first_kept_entry_id`. Typed records `meta_patch` (merged over the meta line on load; goal state via `Agent.persist_meta()`) and `tool_intent` sit between message lines; unknown types are skipped. Trace holds the full-fidelity record
 
 ## Testing
 

{limbo_code-0.2.1 → limbo_code-0.3}/CONTEXT.md

@@ -19,7 +19,8 @@ proposals should name modules with these terms.
 ## Conversation
 
 - **Turn** — one user input through the agent loop until a tool-call-free
-  response (or max_iterations). Turns are the save/trace unit.
+  response (or max_iterations). Turns are the trace unit; the session
+  file is checkpointed at every consistency point inside a turn.
 - **Turn pump** — the non-UI module that runs turns back-to-back
   (`pump.py`, `TurnPump`): pulls events out of the lazy `Agent.run()`
   stream, owns the single-flight busy flag (turns and `/compact`
@@ -28,6 +29,20 @@ proposals should name modules with these terms.
   verify/wrap-up window, teardown race — become one more turn); frontends
   never drain. Frontends are adapters translating its events into UI
   updates.
+- **Conversation** — the live session a frontend drives
+  (`conversation.py`): the current Agent + Turn pump pair, session
+  switching (`/new`, `/sessions`, `/fork`, `/handoff`; the target loads
+  before the current session closes), lifecycle reporting around each
+  run, and the `/goal` verify-proposal flow. The TUI and headless
+  frontends are its adapters; busy is the Turn pump's flag.
+- **Session journal** — the write side of the session file
+  (`journal.py`, `SessionJournal`): which in-memory messages are already
+  on disk, when a checkpoint appends vs rewrites, and the record order
+  that keeps a crash recoverable (summarized messages before their
+  compaction record, `dequeued` after the message carrying the item). The
+  Agent calls its verbs (`checkpoint`, `queued`/`dequeued`,
+  `record_intents`, `compacted`, `patch_meta`); `sessions.py` owns the
+  file format and loading.
 - **Steer** — a user message queued mid-turn, injected at consistency
   points (loop top, turn end, run head). The `SteerQueue` (`steer.py`) owns
   queueing semantics — id generation, FIFO, and the cancel boundary (an

limbo_code-0.3/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.5
+Name: limbo-code
+Version: 0.3
+Summary: A minimal terminal AI coding agent
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygments>=2.17
+Requires-Dist: textual>=8.0
+Requires-Dist: toml>=0.10
+Requires-Dist: tomlkit>=0.13
+Description-Content-Type: text/markdown
+
+# Limbo
+
+**A terminal AI coding agent that is small enough to understand and sturdy
+enough to trust with long work.**
+
+Tell Limbo what you want in plain language. It explores your repository, reads
+and edits files, runs commands, and streams its reasoning and every tool call
+as it goes. When the work runs long, Limbo keeps it safe: every turn is
+journaled to disk, a crash or a closed terminal picks up where it stopped, and
+you can branch, hand off, or replay any session.
+
+![Limbo](docs/assets/limbo-hero.png)
+
+## Who it's for
+
+- **Developers who live in the terminal** and want an agent that fits next to
+  their editor, multiplexer, and dotfiles instead of a separate app.
+- **People who use more than one model.** DeepSeek, Kimi, GLM, OpenAI Codex, or
+  any OpenAI-compatible endpoint, switchable mid-conversation.
+- **Anyone who wants to see what the agent did.** Every request, tool call, and
+  token is recorded and browsable; nothing happens off-screen.
+- **Hackers who want to read the code.** Seven tools, one agent loop, plain
+  JSONL on disk. `AGENTS.md` explains every design decision.
+
+## What you get
+
+### Work that survives
+
+- **Durable sessions.** Messages, tool-call intents, queued follow-ups, and
+  compactions are appended to a JSONL journal as they happen. Kill the process
+  mid-turn and resume: read-only calls that were interrupted are re-run,
+  calls that may have had side effects are flagged so the model checks before
+  retrying, and nothing you queued is lost.
+- **Resume, branch, hand off.** `limbo --continue` or `/sessions` to pick up,
+  `/fork` to try another direction without touching the original, `/handoff`
+  to start a clean context with a written brief that links back.
+- **Long runs stay alive.** Automatic compaction summarizes old turns when the
+  context fills up, while the full record stays in the journal.
+
+### You stay in control
+
+- **`/plan`** puts the agent in read-only mode: it explores and proposes a
+  step-by-step plan, while writes, edits, and mutating shell commands are
+  blocked until you say `/plan off`.
+- **`/goal <task>`** closes the loop: the model proposes a verify command, you
+  confirm it, and Limbo iterates until it passes.
+- **Steer while it works.** Type while a turn is running to redirect it;
+  `Alt+Enter` queues a follow-up for after the task; `Esc` interrupts.
+- **Side channels.** `/btw <question>` asks something quick without polluting
+  the history; `!<command>` runs a shell command yourself, never sent to the
+  model.
+
+### Any model, set up in seconds
+
+- **Guided setup.** On first run with no key, Limbo asks for one and saves it
+  to `~/.limbo/auth.json` (readable only by you). `limbo auth login` verifies a
+  key against the provider before saving; `limbo models` lists the catalog and
+  which models are ready to use.
+- **Switch without restarting.** `Ctrl+L` (or `/model`) opens a searchable
+  picker with recent models first. Pick a model whose provider has no key yet
+  and it asks for one inline. `Shift+Tab` steps through thinking levels.
+- **Three wire formats** (OpenAI completions, Anthropic messages, OpenAI
+  responses) behind one catalog, with per-provider overrides for relays,
+  renamed key variables, and extra headers.
+
+![The Ctrl+L model picker](docs/assets/limbo-models.png)
+
+### Fast turns
+
+- Tool calls issued together run concurrently; edits to the same file are
+  serialized.
+- **Code Mode** (`/code-mode`) collapses the tool catalog into a single
+  `run_code` tool: the model writes one Python program against a generated SDK,
+  turning many round trips into one.
+
+### Nothing hidden
+
+- **`/tracing-viewer`** opens a local web page with a live view of every LLM
+  request, tool call, and token count in the session.
+- **`/export`** dumps the session as a full JSONL log (request bodies, usage,
+  tool results, errors) or as readable Markdown.
+
+### A TUI worth living in
+
+- **Limbo Dusk**, the default theme, with `limbo-dark` and `limbo-light`
+  alternatives, all checked for contrast.
+- **Follows Omarchy.** On an Omarchy desktop Limbo picks up the system theme
+  and switches live when you change it.
+- **Limbo Motion.** Subtle animation that tells the story from unsettled to
+  settled. Set `[ui] motion = "reduced"` or `"off"` if you prefer stillness
+  (SSH sessions default to reduced).
+- `Ctrl+P` command palette, image and file paste with `Ctrl+V`, collapsible
+  tool output with `Ctrl+O`.
+
+### Scriptable
+
+`limbo --headless` gives the same agent as a line-oriented REPL, and
+`limbo --json` prints one JSON event per line so scripts can drive it without
+parsing the screen. Inside the [Herdr](https://herdr.dev) multiplexer, Limbo
+reports its working, idle, and blocked state to the pane.
+
+## Quick start
+
+Requires Python 3.11 or later.
+
+```bash
+pip install limbo-code
+cd ~/code/my-project
+limbo                       # first run asks for an API key
+```
+
+Prefer to set up keys first:
+
+```bash
+limbo auth login            # choose a provider, paste a key, verified and saved
+limbo auth list             # where each provider's key comes from
+limbo models                # what you can run right now
+limbo -m glm-4.7            # one run on a different model
+limbo -m kimi-k3:high       # ...with a thinking level
+```
+
+Then just describe the task: *"find why the login test is flaky and fix it"*.
+
+## Everyday use
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Shift+Enter` | send / new line |
+| `Alt+Enter` | queue a follow-up for after the current task |
+| `Esc` | interrupt |
+| `Ctrl+L` | model picker |
+| `Shift+Tab` | cycle thinking level |
+| `Ctrl+P` | command palette |
+| `Ctrl+S` | sessions |
+| `Ctrl+O` | expand or collapse tool output |
+
+| Command | What it does |
+|---------|--------------|
+| `/model [name]` | switch model (picker when bare); persists to config |
+| `/plan [on\|off]` | read-only mode: explore and propose, mutations blocked |
+| `/goal <task>` | iterate until a confirmed verify command passes |
+| `/code-mode [on\|off]` | one `run_code` tool: a Python program, many tool calls |
+| `/btw <question>` | side question that stays out of history |
+| `/compact` | compact the conversation now |
+| `/sessions` `/new` | switch to a past session, or start fresh |
+| `/fork [n]` | branch into a new session (optionally keep only the first n turns) |
+| `/handoff <brief>` | clean context seeded with a brief, linked to this session |
+| `/export [path]` | full JSONL log, or Markdown when the path ends in `.md` |
+| `/tracing-viewer [id\|off]` | live trace of this session in your browser |
+| `!<command>` | run a shell command yourself, outside the conversation |
+
+From the shell: `limbo --continue` resumes the latest session for the current
+directory, `limbo --resume <id-prefix>` resumes any session.
+
+## Models and providers
+
+| Provider | Wire format | Endpoint |
+|----------|-------------|----------|
+| `deepseek` | openai-completions | `https://api.deepseek.com/v1` |
+| `moonshotai` (Kimi) | openai-completions | `https://api.moonshot.ai/v1` |
+| `kimi-coding` | anthropic-messages | `https://api.kimi.com/coding` |
+| `glm` (GLM Coding Plan) | openai-completions | `https://open.bigmodel.cn/api/coding/paas/v4` |
+| `codex` (OpenAI Codex) | openai-responses | `https://api.openai.com/v1` (relay expected) |
+
+Unknown model ids fall back to generic OpenAI-compatible defaults, and the
+model picker can connect any OpenAI-compatible endpoint. Everything can also
+live in `~/.limbo/config.toml`:
+
+```toml
+[llm]
+model = "deepseek-v4-pro"           # endpoint and key variable come from the catalog
+
+[providers.codex]                   # override one provider only
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"
+headers = { x-relay = "on" }
+
+[ui]
+theme = "auto"                      # Omarchy if installed, else limbo-dusk
+motion = "full"                     # full | reduced | off
+```
+
+## Make it yours
+
+- **Project instructions.** Limbo reads `AGENTS.md` from the working directory
+  and `~/.limbo/AGENTS.md` into its system prompt.
+- **Skills.** Drop a `SKILL.md` into `<project>/.agents/skills/<name>/` or
+  `~/.limbo/skills/<name>/`. The model loads it when the task matches, or you
+  call it as `/<name>`. See [docs/skills.md](docs/skills.md).
+
+## Safety
+
+**There are no fences.** Tools run immediately and unconfined: file tools
+honor absolute paths and symlinks anywhere, there is no sensitive-file
+blocklist, and `bash` runs every command as written, `rm -rf` included. Use
+`/plan` when you only want the agent to look, run Limbo with trusted models,
+and keep it in repositories you can afford to modify or lose.
+
+```toml
+[tools]
+bash_enabled = false     # if you need a hard stop
+```
+
+## Development
+
+```bash
+uv sync        # dev tools are a PEP 735 group, installed by default
+make check     # sync + tests + lint + typecheck
+```
+
+Individually, always `python -m pytest`, never `uv run pytest` (which can fall
+through to a global pytest on `PATH`):
+
+```bash
+uv run python -m pytest tests/ -v
+uv run ruff check src tests
+uv run mypy src
+```
+
+The screenshot above is rendered from the real UI by
+`scripts/readme_hero.py` (`uv run python scripts/readme_hero.py`), so it can't
+drift from what ships.
+
+## Learn more
+
+- [`AGENTS.md`](AGENTS.md): architecture and design decisions
+- [`CONTEXT.md`](CONTEXT.md): domain glossary
+- [`docs/session-management.md`](docs/session-management.md): sessions,
+  recovery, fork and handoff, tracing viewer
+- [`docs/skills.md`](docs/skills.md): writing skills
+- [`design/`](design/): RFCs for headless mode, bang commands, and the UI

limbo_code-0.3/README.md

@@ -0,0 +1,231 @@
+# Limbo
+
+**A terminal AI coding agent that is small enough to understand and sturdy
+enough to trust with long work.**
+
+Tell Limbo what you want in plain language. It explores your repository, reads
+and edits files, runs commands, and streams its reasoning and every tool call
+as it goes. When the work runs long, Limbo keeps it safe: every turn is
+journaled to disk, a crash or a closed terminal picks up where it stopped, and
+you can branch, hand off, or replay any session.
+
+![Limbo](docs/assets/limbo-hero.png)
+
+## Who it's for
+
+- **Developers who live in the terminal** and want an agent that fits next to
+  their editor, multiplexer, and dotfiles instead of a separate app.
+- **People who use more than one model.** DeepSeek, Kimi, GLM, OpenAI Codex, or
+  any OpenAI-compatible endpoint, switchable mid-conversation.
+- **Anyone who wants to see what the agent did.** Every request, tool call, and
+  token is recorded and browsable; nothing happens off-screen.
+- **Hackers who want to read the code.** Seven tools, one agent loop, plain
+  JSONL on disk. `AGENTS.md` explains every design decision.
+
+## What you get
+
+### Work that survives
+
+- **Durable sessions.** Messages, tool-call intents, queued follow-ups, and
+  compactions are appended to a JSONL journal as they happen. Kill the process
+  mid-turn and resume: read-only calls that were interrupted are re-run,
+  calls that may have had side effects are flagged so the model checks before
+  retrying, and nothing you queued is lost.
+- **Resume, branch, hand off.** `limbo --continue` or `/sessions` to pick up,
+  `/fork` to try another direction without touching the original, `/handoff`
+  to start a clean context with a written brief that links back.
+- **Long runs stay alive.** Automatic compaction summarizes old turns when the
+  context fills up, while the full record stays in the journal.
+
+### You stay in control
+
+- **`/plan`** puts the agent in read-only mode: it explores and proposes a
+  step-by-step plan, while writes, edits, and mutating shell commands are
+  blocked until you say `/plan off`.
+- **`/goal <task>`** closes the loop: the model proposes a verify command, you
+  confirm it, and Limbo iterates until it passes.
+- **Steer while it works.** Type while a turn is running to redirect it;
+  `Alt+Enter` queues a follow-up for after the task; `Esc` interrupts.
+- **Side channels.** `/btw <question>` asks something quick without polluting
+  the history; `!<command>` runs a shell command yourself, never sent to the
+  model.
+
+### Any model, set up in seconds
+
+- **Guided setup.** On first run with no key, Limbo asks for one and saves it
+  to `~/.limbo/auth.json` (readable only by you). `limbo auth login` verifies a
+  key against the provider before saving; `limbo models` lists the catalog and
+  which models are ready to use.
+- **Switch without restarting.** `Ctrl+L` (or `/model`) opens a searchable
+  picker with recent models first. Pick a model whose provider has no key yet
+  and it asks for one inline. `Shift+Tab` steps through thinking levels.
+- **Three wire formats** (OpenAI completions, Anthropic messages, OpenAI
+  responses) behind one catalog, with per-provider overrides for relays,
+  renamed key variables, and extra headers.
+
+![The Ctrl+L model picker](docs/assets/limbo-models.png)
+
+### Fast turns
+
+- Tool calls issued together run concurrently; edits to the same file are
+  serialized.
+- **Code Mode** (`/code-mode`) collapses the tool catalog into a single
+  `run_code` tool: the model writes one Python program against a generated SDK,
+  turning many round trips into one.
+
+### Nothing hidden
+
+- **`/tracing-viewer`** opens a local web page with a live view of every LLM
+  request, tool call, and token count in the session.
+- **`/export`** dumps the session as a full JSONL log (request bodies, usage,
+  tool results, errors) or as readable Markdown.
+
+### A TUI worth living in
+
+- **Limbo Dusk**, the default theme, with `limbo-dark` and `limbo-light`
+  alternatives, all checked for contrast.
+- **Follows Omarchy.** On an Omarchy desktop Limbo picks up the system theme
+  and switches live when you change it.
+- **Limbo Motion.** Subtle animation that tells the story from unsettled to
+  settled. Set `[ui] motion = "reduced"` or `"off"` if you prefer stillness
+  (SSH sessions default to reduced).
+- `Ctrl+P` command palette, image and file paste with `Ctrl+V`, collapsible
+  tool output with `Ctrl+O`.
+
+### Scriptable
+
+`limbo --headless` gives the same agent as a line-oriented REPL, and
+`limbo --json` prints one JSON event per line so scripts can drive it without
+parsing the screen. Inside the [Herdr](https://herdr.dev) multiplexer, Limbo
+reports its working, idle, and blocked state to the pane.
+
+## Quick start
+
+Requires Python 3.11 or later.
+
+```bash
+pip install limbo-code
+cd ~/code/my-project
+limbo                       # first run asks for an API key
+```
+
+Prefer to set up keys first:
+
+```bash
+limbo auth login            # choose a provider, paste a key, verified and saved
+limbo auth list             # where each provider's key comes from
+limbo models                # what you can run right now
+limbo -m glm-4.7            # one run on a different model
+limbo -m kimi-k3:high       # ...with a thinking level
+```
+
+Then just describe the task: *"find why the login test is flaky and fix it"*.
+
+## Everyday use
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Shift+Enter` | send / new line |
+| `Alt+Enter` | queue a follow-up for after the current task |
+| `Esc` | interrupt |
+| `Ctrl+L` | model picker |
+| `Shift+Tab` | cycle thinking level |
+| `Ctrl+P` | command palette |
+| `Ctrl+S` | sessions |
+| `Ctrl+O` | expand or collapse tool output |
+
+| Command | What it does |
+|---------|--------------|
+| `/model [name]` | switch model (picker when bare); persists to config |
+| `/plan [on\|off]` | read-only mode: explore and propose, mutations blocked |
+| `/goal <task>` | iterate until a confirmed verify command passes |
+| `/code-mode [on\|off]` | one `run_code` tool: a Python program, many tool calls |
+| `/btw <question>` | side question that stays out of history |
+| `/compact` | compact the conversation now |
+| `/sessions` `/new` | switch to a past session, or start fresh |
+| `/fork [n]` | branch into a new session (optionally keep only the first n turns) |
+| `/handoff <brief>` | clean context seeded with a brief, linked to this session |
+| `/export [path]` | full JSONL log, or Markdown when the path ends in `.md` |
+| `/tracing-viewer [id\|off]` | live trace of this session in your browser |
+| `!<command>` | run a shell command yourself, outside the conversation |
+
+From the shell: `limbo --continue` resumes the latest session for the current
+directory, `limbo --resume <id-prefix>` resumes any session.
+
+## Models and providers
+
+| Provider | Wire format | Endpoint |
+|----------|-------------|----------|
+| `deepseek` | openai-completions | `https://api.deepseek.com/v1` |
+| `moonshotai` (Kimi) | openai-completions | `https://api.moonshot.ai/v1` |
+| `kimi-coding` | anthropic-messages | `https://api.kimi.com/coding` |
+| `glm` (GLM Coding Plan) | openai-completions | `https://open.bigmodel.cn/api/coding/paas/v4` |
+| `codex` (OpenAI Codex) | openai-responses | `https://api.openai.com/v1` (relay expected) |
+
+Unknown model ids fall back to generic OpenAI-compatible defaults, and the
+model picker can connect any OpenAI-compatible endpoint. Everything can also
+live in `~/.limbo/config.toml`:
+
+```toml
+[llm]
+model = "deepseek-v4-pro"           # endpoint and key variable come from the catalog
+
+[providers.codex]                   # override one provider only
+base_url = "https://my-relay.example.com/v1"
+api_key_env = "CODEX_API_KEY"
+headers = { x-relay = "on" }
+
+[ui]
+theme = "auto"                      # Omarchy if installed, else limbo-dusk
+motion = "full"                     # full | reduced | off
+```
+
+## Make it yours
+
+- **Project instructions.** Limbo reads `AGENTS.md` from the working directory
+  and `~/.limbo/AGENTS.md` into its system prompt.
+- **Skills.** Drop a `SKILL.md` into `<project>/.agents/skills/<name>/` or
+  `~/.limbo/skills/<name>/`. The model loads it when the task matches, or you
+  call it as `/<name>`. See [docs/skills.md](docs/skills.md).
+
+## Safety
+
+**There are no fences.** Tools run immediately and unconfined: file tools
+honor absolute paths and symlinks anywhere, there is no sensitive-file
+blocklist, and `bash` runs every command as written, `rm -rf` included. Use
+`/plan` when you only want the agent to look, run Limbo with trusted models,
+and keep it in repositories you can afford to modify or lose.
+
+```toml
+[tools]
+bash_enabled = false     # if you need a hard stop
+```
+
+## Development
+
+```bash
+uv sync        # dev tools are a PEP 735 group, installed by default
+make check     # sync + tests + lint + typecheck
+```
+
+Individually, always `python -m pytest`, never `uv run pytest` (which can fall
+through to a global pytest on `PATH`):
+
+```bash
+uv run python -m pytest tests/ -v
+uv run ruff check src tests
+uv run mypy src
+```
+
+The screenshot above is rendered from the real UI by
+`scripts/readme_hero.py` (`uv run python scripts/readme_hero.py`), so it can't
+drift from what ships.
+
+## Learn more
+
+- [`AGENTS.md`](AGENTS.md): architecture and design decisions
+- [`CONTEXT.md`](CONTEXT.md): domain glossary
+- [`docs/session-management.md`](docs/session-management.md): sessions,
+  recovery, fork and handoff, tracing viewer
+- [`docs/skills.md`](docs/skills.md): writing skills
+- [`design/`](design/): RFCs for headless mode, bang commands, and the UI