limbo-code 0.2.2__tar.gz → 0.3.5__tar.gz

limbo_code-0.3.5/AGENTS.md

@@ -0,0 +1,168 @@
+# Limbo — Agent Guide
+
+**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). `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
+
+```bash
+uv sync                               # installs runtime + dev tools (PEP 735 dev group, on by default)
+uv run limbo --workdir /path/to/project   # config: ~/.limbo/config.toml
+```
+
+Prefer `uv` over `pip`: dev tools (pytest/ruff/mypy) are a `[dependency-groups]`
+group, NOT an extra — `pip install -e ".[dev]"` no longer exists. `pip install -e .`
+still works for a runtime-only install.
+
+## Architecture
+
+```
+src/limbo/
+├── app.py            # CLI entry: args, config, launch
+├── config.py         # Pydantic config: llm/ui/tools/compaction/providers
+├── models.py         # Message, Attachment, ToolResult, LLMEvent
+├── agent.py          # Conversation loop (see below)
+├── attachments.py    # Attachment policy: vision gate, inline vs path-reference degrade
+├── compaction.py     # Context compaction decision/prompt logic (LIM-14)
+├── history.py        # tool_call↔result pairing + resume repair
+├── model_switch.py   # /model domain logic: validate, swap client, persist (UI is an adapter)
+├── code_mode.py      # Code Mode (/code-mode on|off): SDK rendering + CODE_ONLY instruction
+│                     # (deepseek-harness parity: catalog collapses to run_code)
+├── prompt.py         # System-prompt assembly (tools section derived from the registry)
+├── steer.py          # Mid-turn steer queue (LIM-20): queueing semantics, cancel boundary
+├── goal.py           # /goal closed-loop state machine, prompt templates, verify executor (LIM-40)
+├── pump.py           # Turn pump (frontend-agnostic, non-UI): single-flight busy flag,
+│                     # steer follow-up drain, /compact mini-turn, goal closed loop
+├── 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
+├── 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, the subagent supervisor
+│                     # (subscribe/start_background/take_wake_input)
+├── 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 + 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)
+├── daily_skills/     # Bundled daily starter skills (ported from hermes-agent, MIT; excluded
+│                     # from ruff/mypy)
+├── daily.py          # Daily mode notices (docs/daily-mode.md); the posture itself is
+│                     # ToolRegistry.daily_mode + prompt.py + SessionMeta.daily_mode
+├── memory.py         # Persistent memory (~/.limbo/memory/USER.md, NOTES.md): MemoryStore
+│                     # (capped, atomic batch ops, .bak), frozen per-session MemorySnapshot
+├── subagents/        # Background subagents (docs/subagents.md): board.py (event-sourced
+│                     # task board + pure reconcile()), supervisor.py (scheduler, runners,
+│                     # notice delivery, user/main verbs), tools.py (main: plan_tasks/
+│                     # task_status/task_send/answer/task_control; child: checkpoint/need/
+│                     # ask_main/finish/propose_task), profiles.py (agent profiles),
+│                     # project_scan.py (<project_facts>), hooks.py (read-only/no-edit/path
+│                     # claims), worktree.py, commands.py (/task /agents @name), events.py
+├── llm/              # catalog.py (provider/model specs), factory.py (dialect→client),
+│                     # openai_client.py, anthropic_client.py, responses_client.py, retry.py, sse.py,
+│                     # usage.py (token accounting: usage normalization + prompt-size estimation),
+│                     # 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), 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),
+│                     # web_search.py (registered only when the search provider has a key),
+│                     # daily mode only: web_fetch.py, memory.py, session_search.py,
+│                     # ask_user.py (end_turn), skill_manage.py (writes ~/.limbo/daily/skills)
+├── websearch/        # pluggable web-search backends: base.py (SearchProvider/SearchResult),
+│                     # deepseek.py (+ key inheritance from the deepseek model provider), PROVIDERS
+└── ui/               # app.py + app.tcss (ALL styles here; theme vars only, no bare hex),
+                      # theme.py (limbo-dark/-light, RFC LIM-16), daily_look.py (daily mode
+                      # "Limbo Dawn": <theme>+daily warm variant, app.set_daily_look), commands.py (slash registry
+                      # + resolve(): the single builtin-vs-skill collision site), path_input.py
+                      # ('/'-path fallback), paste_store.py (pure paste/attachment marker
+                      # state machine; the input widget is its adapter),
+                      # screens/ (main, session_picker, model_picker, game2048),
+                      # widgets/ (chat, input, status_bar, tool_card, command_menu)
+```
+
+## Agent Loop
+
+- `Agent.run()` yields `AgentEvent`: `TextDelta`, `ThinkingDelta`, `ToolCallRequest`, `ToolResultEvent`, `ErrorEvent`, `CompactionEvent`, `UsageUpdate`, `SteerEvent`
+- 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. 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)
+- 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
+
+Providers/models live in `llm/catalog.py`; unknown models get generic OpenAI-compatible defaults. Resolution: `[providers.<id>]` overrides → explicit `[llm]` values → catalog defaults → env-var API keys.
+
+```toml
+[llm]        # model, api_key, base_url, temperature, max_iterations,
+             # max_tokens, thinking_effort, max_retries, timeout, ...
+[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)
+[subagents]  # enabled, auto = "off"|"suggest"|"on", max_parallel = 3, max_tasks = 12,
+             # task_token_budget, cheap_model, wake_main_on, on_dep_fail, on_resume
+[daily]      # workdir = "~/limbo-daily", model, memory, user_chars, notes_chars,
+             # memory_nudge_turns, learn_after_tool_calls, fetch_max_chars, fetch_timeout
+[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: 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); daily sessions also see the bundled `src/limbo/daily_skills/` (lowest) and `~/.limbo/daily/skills/` (highest), coding sessions never do — 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, 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 /daily-mode /memory /learn /help /2048 /goal /agents /task` + skill commands; `@<agent> text` messages a subagent. '/'-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.
+
+Subagents (`subagents/`, docs/subagents.md): the main agent's `plan_tasks` creates tasks on the board (suggest mode: `PlanPicker` asks the user first); the `Supervisor` runs each as a child `Agent` with its own session file, gated by profile hooks. Child tools that end the turn (`need`, `ask_main`, `finish`) return `ToolResult(end_turn=True)`. Notices reach the main agent as one `source="subagent"` steer item; an idle main agent is woken through `MainWake` → `Conversation.take_wake_input()`. Board records live in the main session file (`type: "task"`), so the board survives restarts; tasks running at exit come back paused (`on_resume`).
+
+Daily mode (`limbo daily` / `--daily` / `/daily-mode on|off`, docs/daily-mode.md): a session posture like Code Mode — same loop, a general-assistant system prompt, plus `web_fetch` and `memory` tools; persisted as `SessionMeta.daily_mode`, `/new` keeps the current mode. Memory is a snapshot taken when the Agent is built: `USER.md` and `NOTES.md` enter daily-mode prompts only (coding sessions never see memory); `memory` tool writes reach disk at once but the prompt changes only next session (prefix cache stays intact). `/learn` (and auto after `learn_after_tool_calls` tool calls) plans a `skill-reviewer` fork subagent whose only write tool is `skill_manage`; daily children inherit daily mode minus `MAIN_ONLY_TOOLS`.
+
+## Key Decisions
+
+- Async agent, sync tools via `asyncio.to_thread()`
+- Code Mode (`/code-mode on|off`): `ToolRegistry.code_mode` collapses
+  `definitions()` to `[run_code]`; `RunCodeTool` runs a model-written Python
+  program on a fresh event loop, forwarding `tools.*` sub-calls through the
+  same registry. Only the curated program output (print + return) enters
+  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 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
+
+```bash
+make check                          # single entrypoint: sync + tests + lint + type check
+```
+
+Or individually — always `python -m pytest`, never bare `uv run pytest` (which
+silently falls through to a global pytest on PATH when the venv lacks pytest):
+
+```bash
+uv sync                             # first time / after pulling; dev group is default
+uv run python -m pytest tests/ -v   # pytest-asyncio, respx HTTP mocks, pytest-textual-snapshot
+uv run ruff check src tests && uv run mypy src  # lint + type check
+uv run python -m pytest --snapshot-update  # after intentional visual changes; review the SVG diff
+```
+
+## Adding Things
+
+- **Tool**: subclass `BaseTool` in `tools/<name>.py` (`name`/`description`/`parameters` + `run()`; use `resolve_existing()`/`resolve_creatable()`, raise `ToolError`), register in `ToolRegistry.__init__()`, wrap mutations in `mutation_lock_for(path)`, add `tests/tools/test_<name>.py`
+- **Web-search backend**: subclass `SearchProvider` in `websearch/<id>.py` with a `build(config)` factory (None when it has no key), add it to `websearch.PROVIDERS`; users pick it with `[web_search] provider`
+- **Provider/model**: add specs in `llm/catalog.py`; new wire format → implement `LLMClient` + `register_client()` in `llm/factory.py`. User-specific endpoint/key tweaks belong in `[providers.<id>]` config, not the catalog

{limbo_code-0.2.2 → limbo_code-0.3.5}/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
@@ -45,6 +60,26 @@ proposals should name modules with these terms.
   (converging on the latest config model), persist to config.toml. The UI
   screen is an adapter translating verdicts into chat messages.
 
+## Subagents
+
+- **Task board** — the delegated work of one main session
+  (`subagents/board.py`): tasks with status, `depends_on` (dependency
+  edges: a failure notifies by default), `owner` (ownership edges: a
+  failure cascades), waits, checkpoints, questions and outcomes.
+  Event-sourced into the main session file; `reconcile()` is the pure
+  scheduling rule.
+- **Subagent** — a child Agent working on one task with its own context and
+  session file. It reports through checkpoint / need / ask_main / finish
+  and never plans tasks itself (depth 1).
+- **Profile** — what kind of subagent a task gets (tools, model, prompt);
+  built-in, user (`~/.limbo/agents`) or project (`.agents/agents`).
+- **Supervisor** — owns the board, the running subagents and notice
+  delivery for one Conversation (`subagents/supervisor.py`).
+- **Notice** — a subagent event for the main agent: result, question,
+  alert, info (delivered, at most once) or progress (UI only). Delivered as
+  one `<subagent_updates>` steer item; questions and alerts wake an idle
+  main agent, results wait until the wave is done.
+
 ## Safety
 
 Limbo has no safety fences: file tools are not scoped to the workdir,

limbo_code-0.3.5/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.5
+Name: limbo-code
+Version: 0.3.5
+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
+Provides-Extra: daily
+Requires-Dist: pypdf>=4.0; extra == 'daily'
+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.
+- **Background subagents.** The agent can split work into tasks that run in
+  parallel with their own context: they checkpoint, wait on each other when
+  they discover a dependency, and report back. You approve the plan, watch
+  the board in `/agents`, and pause, cancel or talk to any of them with
+  `/task` or `@name`, or just ask the main agent.
+- **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`.
+
+### Daily mode for everything else
+
+`limbo daily` (or `/daily-mode on`) turns Limbo into an everyday assistant for
+non-coding work, in its own working directory:
+
+- **Memory.** `USER.md` (who you are) and `NOTES.md` (what it learned) under
+  `~/.limbo/memory/`, loaded into daily sessions only, never into coding ones.
+- **More tools.** `web_fetch` reads pages and PDFs, `session_search` recalls
+  past conversations, and `ask_user` asks you a multiple-choice question.
+- **A starter pack of skills** for PDFs, Word, Excel, slides, citations,
+  meeting notes, weekly reviews, YouTube and arXiv. Daily mode has its own
+  skill directory (`~/.limbo/daily/skills/`) that coding sessions never see.
+- **It learns.** `/learn`, or an automatic review after a long stretch of
+  work, has a background subagent write what it learned into skills. Every
+  write lands in the daily skill directory and keeps a `.bak`.
+
+See [docs/daily-mode.md](docs/daily-mode.md).
+
+### 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 |
+| `/agents` `/task` `@name` | background subagents: the task board, direct control, talk to one |
+| `/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
+```
+
+### Web search
+
+The `web_search` tool is offered whenever its provider has a key. The only
+provider today is DeepSeek
+([search API](https://api-docs.deepseek.com/guides/search)); without its own
+key it reuses the DeepSeek model key (`[providers.deepseek]`, `limbo auth
+login`, `$DEEPSEEK_API_KEY`, or `[llm] api_key` while a DeepSeek model is
+active).
+
+```toml
+[web_search]
+provider = "deepseek"    # backends live in limbo.websearch.PROVIDERS
+api_key = "sk-..."       # optional: a separate key just for search
+count = 10               # default results per search
+enabled = true
+```
+
+## 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.
+
+## Acknowledgements
+
+Limbo borrows openly from other agents. Thank you to:
+
+- **[pi](https://github.com/badlogic/pi-mono) and pi-durable.** The durable
+  session design comes from pi-durable: the "commit the intent, then the
+  effect" journal, the replay policy for tool calls interrupted by a crash,
+  the placeholders that say what is known about an unfinished call, the
+  steer and follow-up inbox (`Alt+Enter`), the task graph edges behind
+  background subagents, and context overflow detection. From the pi coding
+  agent itself: the built-in tool behavior (output limits, multi-edit,
+  process-tree kill, ripgrep), the provider conventions and model catalog,
+  compaction and the session entry model, and collapsing large pastes.
+- **[Crush](https://github.com/charmbracelet/crush)** by Charm. The Limbo
+  Dusk TUI was designed after Crush: the gradient wordmark, `╱` dialog rules,
+  Limbo Motion (its staggered entrance is borrowed directly), the `Ctrl+P`
+  command palette and the `Ctrl+S` session picker.
+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** by Nous
+  Research. Daily mode is modeled on Hermes: the `USER.md` / `NOTES.md`
+  memory with its frozen per-session snapshot and the memory nudge,
+  `session_search`, `ask_user`, and skill self-learning (the skill reviewer's
+  prompt is adapted from Hermes). The bundled daily skills in
+  `src/limbo/daily_skills/` are ported from Hermes under the MIT license, and
+  each keeps its `LICENSE`.
+
+## 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
+- [`docs/daily-mode.md`](docs/daily-mode.md): daily mode, memory and
+  self-learning skills
+- [`docs/subagents.md`](docs/subagents.md): background subagents, the task
+  board and how to steer them
+- [`design/`](design/): RFCs for headless mode, bang commands, and the UI