comodor 0.1.0__tar.gz

comodor-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# python
+__pycache__/
+*.py[cod]
+.venv/
+.comodor/
+*.db
+*.db-shm
+*.db-wal
+.env
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+
+# The comodor.ai site is a separate deliverable and is deliberately not part
+# of this repository. It lives in its own tree.
+website/
+node_modules/
+.next/
+out/
+next-env.d.ts
+*.tsbuildinfo
+.env*.local
+npm-debug.log*
+dist/

comodor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Comodor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

comodor-0.1.0/PKG-INFO

@@ -0,0 +1,313 @@
+Metadata-Version: 2.5
+Name: comodor
+Version: 0.1.0
+Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
+Project-URL: Homepage, https://comodor.ai
+Project-URL: Repository, https://github.com/ifekri/comodor
+Author: Comodor
+License: MIT
+License-File: LICENSE
+Keywords: agent,coding-assistant,llm,rich,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Comodor
+
+**It learns the way you correct it.** — [comodor.ai](https://comodor.ai)
+
+A terminal coding agent that reads and edits your files, runs your tests,
+searches the web, and works through multi-step tasks on its own — inside a Rich
+interface that reflows cleanly from a 40-column SSH window to an ultrawide
+monitor.
+
+What makes it different is **Reflex**: Comodor watches what you *do* — the code
+you rewrite, the edits you undo, the commands you refuse — and turns that into
+rules, with no model call and no perceptible delay. Fix something once, and the
+next answer already obeys.
+
+```
+› create defaults.py with 6 string constants
+◈ learned: Use single quotes for string literals.   (/rules forget 1 to undo)
+```
+
+That is a real transcript. The turn before it, Comodor wrote double quotes and the
+file was edited by hand. Nobody told it anything.
+
+```
+┌─ History ──────────────┐ ┌─ Chat ───────────────────────────────────────────────┐
+│ TASKS 2/4 ──────────── │ │ › add a health endpoint and a test for it            │
+│ ● read the app factory │ │ ◈ recalled 3 lessons                                 │
+│ ● add the /health rou… │ │                                                      │
+│ ◐ write the test       │ │ I'll add the route, then a test.                     │
+│ ○ run the suite        │ │                                                      │
+│                        │ │ ⚙ edit src/app.py  0.2s                              │
+│                        │ │   + @app.get('/health')                              │
+│                        │ │ ⚙ run: pytest -q  3.4s                               │
+│                        │ │   4 passed in 0.42s                                  │
+└────────────────────────┘ └──────────────────────────────────────────────────────┘
+┌────────────────────────┐ ┌──────────────────────────────────────────┐
+│ Context:1M GW: Disable │ │ Prompt Here ...                          │    SEND
+│ Mode : Act Loop : On   │ │ ──────────────────────────────────────── │
+│ ███░░░░░░░░░░░░░░░░░░░ │ │ Provider : Openrouter | Model : …        │   ATTACH
+│ 143K used $0.041  ◈7   │ │                                          │
+│ ┌────────────────────┐ │ │                                          │    MODE
+│ │      Settings      │ │ └──────────────────────────────────────────┘
+└────────────────────────┘
+```
+
+## Install
+
+**macOS / Linux**
+
+```bash
+curl -fsSL https://comodor.ai/install.sh | sh
+```
+
+**Windows**
+
+```powershell
+irm https://comodor.ai/install.ps1 | iex
+```
+
+The installer uses whichever of `uv`, `pipx` or `pip` you already have. If you
+would rather run one yourself:
+
+```bash
+uv tool install comodor          # fastest; fetches a Python if you have none
+pipx install comodor             # isolated and on your PATH
+pip install comodor              # into the current environment
+pipx install git+https://github.com/ifekri/comodor    # latest commit
+```
+
+Requires Python 3.11+. The only runtime dependencies are `rich` and
+`python-dotenv` — the HTTP client is part of the package.
+
+**From a clone**
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows;  source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Configure
+
+Copy `.env.example` to `.env` and fill in whichever provider you use:
+
+```bash
+OPENROUTER_API_KEY=sk-or-v1-…
+```
+
+Comodor speaks the OpenAI-compatible protocol (OpenRouter, Xiaomi MiMo, DeepSeek,
+Groq, Together, Ollama, LM Studio) and the native Anthropic Messages API. It
+enables a provider as soon as it finds a key.
+
+No key yet? `comodor --demo` runs the whole interface against a scripted offline
+provider.
+
+## Use
+
+```bash
+comodor                          # the interface
+comodor --demo                   # offline walkthrough, no key needed
+comodor run "fix the failing test" --yes    # one task, headless, for scripts
+comodor run "audit this module" --json      # machine-readable result
+comodor doctor                   # what is configured and what is reachable
+```
+
+### Keys
+
+| Key | Action |
+|---|---|
+| `Enter` | send · `Ctrl+J` newline |
+| `Esc` | stop the agent |
+| `F1` … `F5` | help · sidebar · mode · loop · gateway |
+| `Ctrl+O` | attach a file |
+| `PgUp` / `PgDn` | scroll the transcript |
+| `Ctrl+C` | stop; twice to quit |
+
+`!command` runs a shell command directly. `@path` attaches a file to your
+message. Buttons and the sidebar are clickable where the terminal supports it.
+
+### Commands
+
+`/help` `/model` `/provider` `/mode` `/loop` `/gw` `/rules` `/progress` `/memory`
+`/teach` `/skills` `/good` `/bad` `/undo` `/cost` `/export` `/theme` `/settings`
+`/approve` `/save` `/attach` `/clear` `/resume` `/quit`
+
+## The three switches
+
+**Mode** decides what the agent may touch.
+
+- **Act** — the full tool set; it can change your project.
+- **Plan** — read-only. Write tools are not merely blocked, they are never shown
+  to the model, so you get a plan rather than a thwarted attempt to edit.
+- **Chat** — no tools at all.
+
+**Loop** decides whether it keeps going. On, the agent iterates until the task is
+done or a guard trips (steps, wall clock, spend). Off, it answers once.
+
+**GW** is the model gateway. Disabled — the default — every request goes to the
+provider you picked, so what the status bar says is what answered. Enabled, it
+ranks healthy providers by cost, speed or quality and fails over when a call
+breaks. A stream that has already produced output is never retried elsewhere:
+duplicating half an answer is worse than reporting the failure.
+
+## Reflex — a two-speed brain
+
+Most agents remember what you *tell* them. Comodor learns from what you *fix*.
+
+**Reflex is the fast lane.** Deterministic, model-free, sub-millisecond, always
+on. It reads five signals, all of them free because you produce them just by
+working:
+
+| signal | what it means |
+|---|---|
+| you rewrite a file the agent wrote | the diff *is* the preference — quotes, indentation, annotations, verbosity |
+| you `/undo` a change | an outright rejection |
+| you deny a permission | one command this user does not want run |
+| you ask the same thing twice | the answer missed |
+| a tool fails the same way twice | a pitfall in this environment, verified |
+
+Each becomes a **rule** with its evidence attached — not "I think you prefer
+single quotes" but `31 of 34 literals` — and how much evidence a rule needs
+depends on where it came from. Watching your codebase is weak proof, so it takes
+four agreeing observations. You editing the agent's output is a deliberate
+statement, so it takes two. Telling it outright takes one.
+
+Detection runs at the *start* of a turn, not the end. That is what makes the
+correction land immediately rather than a task later.
+
+**Reflection is the slow lane** — the original LLM pass that distils prose
+lessons from an episode. It still runs, in the background, and it is now
+optional. Switch it off, work offline, use a cheap model: Reflex keeps learning
+either way, because it never needed a model at all.
+
+Everything is inspectable and reversible:
+
+```
+/rules              browse rules with their evidence; pin, disable or drop one
+/rules teach Never add comments unless asked.
+/rules export       writes .comodor/house-rules.md for the team to commit
+/memory             the distilled lessons, same controls
+/teach  /good  /bad
+```
+
+## Proof, not claims: `/progress`
+
+"Gets better over time" is what every tool says. Comodor shows the numbers.
+
+```
+◈ Steps per task down 40% since the first tasks in this project.
+
+metric                trend                            now  vs first
+Steps per task        ▇██▇▇▆▇▅▅▅▅▆▄▅▄▅▄▄▂▄▂▁▂▂▂▁▁▁▁▁   5.3      ↓40%
+Corrections per task  ████▆▇▆█▆▆▆▇▆▆▅▃▃▅▆▆▅▃▆▃▆▃▂▁▁▃   0.9      ↓65%
+Approvals asked       █▇▇▇▇▇▇▇▇▇▅▅▅▅▅▅▅▅▅▅▃▃▃▃▃▃▃▃▃▁   0.8      ↓73%
+Tokens per task       █▇████▇▇▆▆▆▆▆▆▅▅▄▄▅▃▃▄▄▃▂▂▂▂▂▁  6.4K      ↓29%
+First-try success     ██▁███████████████████████████  100%      ↑8pp
+
+brain  7 rules · 23 lessons · 70 corrections learned from
+history  40 tasks over 2 days
+```
+
+The panel is built to be honest, which is what makes it worth showing: with too
+little history it says so, a metric that has not moved is reported as unchanged,
+a rate moves in percentage points rather than as a percentage of a percentage,
+and a fall from 0.4 to 0 is never allowed to headline as "down 100%".
+
+## Speed
+
+Memory sits between pressing Enter and the first token, so it is measured and
+budgeted. Against a deliberately worst-case corpus on a normal laptop:
+
+| operation | before | now |
+|---|---|---|
+| recall, 3,000 lessons | 2.0 ms | 0.38 ms |
+| recall, 20,000 lessons | — | **0.38 ms** (flat) |
+| deduplication, 3,000 lessons | 22 ms | 0.25 ms |
+| pinned lookup, 20,000 lessons | 8.9 ms | 0.10 ms |
+| recording reinforcement | 0.04 ms | 0.001 ms |
+
+Three things get it there. A **RAM mirror** holds every lesson with its tokens
+pre-computed and an inverted index over them, so a lookup touches only the
+documents sharing a word with the query — and the candidate set is capped, which
+is why the cost stops growing with the corpus. A **background writer** batches
+commits so nothing user-facing ever waits on the disk. And **speculative recall**
+runs the whole ranking while you are still typing, so on the turn itself it
+costs nothing at all.
+
+`tests/test_performance.py` enforces these as ceilings. A change that makes
+memory slow fails the suite.
+
+## Safety
+
+- **Risk tiers.** Reads never prompt. Writes show a coloured diff and ask.
+  Commands and network calls always ask.
+- **Checkpoints.** Files are snapshotted before any change; `/undo` restores them.
+- **A deny list** no prompt can talk past, for the handful of commands that are
+  never acceptable.
+- **Workspace confinement.** Writes outside the project are refused by default.
+- **Redaction.** API keys and tokens are stripped from logs, transcripts and
+  exports.
+- `--yes` exists for CI. Headless runs refuse to change anything without it.
+
+## Any terminal, any size
+
+The layout is recomputed every frame from the terminal size, so resizing just
+works.
+
+| Width | Layout |
+|---|---|
+| `< 60` | one column; sidebar on `F2` |
+| `60–99` | narrow sidebar, compact status |
+| `100–139` | the reference design |
+| `≥ 140` | wide sidebar, roomier transcript |
+
+Below 40×12 it says so plainly rather than drawing a corrupted screen. `--ascii`
+drops box-drawing glyphs for terminals that cannot render them, and a monochrome
+terminal gets a monochrome theme automatically.
+
+## Layout of the code
+
+```
+src/comodor/
+├─ net/         zero-dependency HTTP client + SSE reader
+├─ providers/   OpenAI-compatible, Anthropic, offline fake, and the gateway
+├─ agent/       the reason/act loop, context budgeting, prompts
+├─ tools/       files, search, shell, python, web, task list
+├─ safety/      permissions, checkpoints, redaction
+├─ learning/    the brain: hot index, async writer, signals, rules, progress
+├─ session/     persistence and export
+└─ ui/          layout, theme, widgets, raw input, the app loop
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+comodor preview 120x34            # render one frame at a fixed size
+comodor preview 60x20 --svg out.svg
+```
+
+The test suite runs the whole agent against a scripted provider, so there is no
+network and no spend, and renders the interface at a range of sizes to prove the
+responsive layout holds.
+
+## Licence
+
+MIT.

comodor-0.1.0/README.md

@@ -0,0 +1,288 @@
+# Comodor
+
+**It learns the way you correct it.** — [comodor.ai](https://comodor.ai)
+
+A terminal coding agent that reads and edits your files, runs your tests,
+searches the web, and works through multi-step tasks on its own — inside a Rich
+interface that reflows cleanly from a 40-column SSH window to an ultrawide
+monitor.
+
+What makes it different is **Reflex**: Comodor watches what you *do* — the code
+you rewrite, the edits you undo, the commands you refuse — and turns that into
+rules, with no model call and no perceptible delay. Fix something once, and the
+next answer already obeys.
+
+```
+› create defaults.py with 6 string constants
+◈ learned: Use single quotes for string literals.   (/rules forget 1 to undo)
+```
+
+That is a real transcript. The turn before it, Comodor wrote double quotes and the
+file was edited by hand. Nobody told it anything.
+
+```
+┌─ History ──────────────┐ ┌─ Chat ───────────────────────────────────────────────┐
+│ TASKS 2/4 ──────────── │ │ › add a health endpoint and a test for it            │
+│ ● read the app factory │ │ ◈ recalled 3 lessons                                 │
+│ ● add the /health rou… │ │                                                      │
+│ ◐ write the test       │ │ I'll add the route, then a test.                     │
+│ ○ run the suite        │ │                                                      │
+│                        │ │ ⚙ edit src/app.py  0.2s                              │
+│                        │ │   + @app.get('/health')                              │
+│                        │ │ ⚙ run: pytest -q  3.4s                               │
+│                        │ │   4 passed in 0.42s                                  │
+└────────────────────────┘ └──────────────────────────────────────────────────────┘
+┌────────────────────────┐ ┌──────────────────────────────────────────┐
+│ Context:1M GW: Disable │ │ Prompt Here ...                          │    SEND
+│ Mode : Act Loop : On   │ │ ──────────────────────────────────────── │
+│ ███░░░░░░░░░░░░░░░░░░░ │ │ Provider : Openrouter | Model : …        │   ATTACH
+│ 143K used $0.041  ◈7   │ │                                          │
+│ ┌────────────────────┐ │ │                                          │    MODE
+│ │      Settings      │ │ └──────────────────────────────────────────┘
+└────────────────────────┘
+```
+
+## Install
+
+**macOS / Linux**
+
+```bash
+curl -fsSL https://comodor.ai/install.sh | sh
+```
+
+**Windows**
+
+```powershell
+irm https://comodor.ai/install.ps1 | iex
+```
+
+The installer uses whichever of `uv`, `pipx` or `pip` you already have. If you
+would rather run one yourself:
+
+```bash
+uv tool install comodor          # fastest; fetches a Python if you have none
+pipx install comodor             # isolated and on your PATH
+pip install comodor              # into the current environment
+pipx install git+https://github.com/ifekri/comodor    # latest commit
+```
+
+Requires Python 3.11+. The only runtime dependencies are `rich` and
+`python-dotenv` — the HTTP client is part of the package.
+
+**From a clone**
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows;  source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pytest -q
+```
+
+## Configure
+
+Copy `.env.example` to `.env` and fill in whichever provider you use:
+
+```bash
+OPENROUTER_API_KEY=sk-or-v1-…
+```
+
+Comodor speaks the OpenAI-compatible protocol (OpenRouter, Xiaomi MiMo, DeepSeek,
+Groq, Together, Ollama, LM Studio) and the native Anthropic Messages API. It
+enables a provider as soon as it finds a key.
+
+No key yet? `comodor --demo` runs the whole interface against a scripted offline
+provider.
+
+## Use
+
+```bash
+comodor                          # the interface
+comodor --demo                   # offline walkthrough, no key needed
+comodor run "fix the failing test" --yes    # one task, headless, for scripts
+comodor run "audit this module" --json      # machine-readable result
+comodor doctor                   # what is configured and what is reachable
+```
+
+### Keys
+
+| Key | Action |
+|---|---|
+| `Enter` | send · `Ctrl+J` newline |
+| `Esc` | stop the agent |
+| `F1` … `F5` | help · sidebar · mode · loop · gateway |
+| `Ctrl+O` | attach a file |
+| `PgUp` / `PgDn` | scroll the transcript |
+| `Ctrl+C` | stop; twice to quit |
+
+`!command` runs a shell command directly. `@path` attaches a file to your
+message. Buttons and the sidebar are clickable where the terminal supports it.
+
+### Commands
+
+`/help` `/model` `/provider` `/mode` `/loop` `/gw` `/rules` `/progress` `/memory`
+`/teach` `/skills` `/good` `/bad` `/undo` `/cost` `/export` `/theme` `/settings`
+`/approve` `/save` `/attach` `/clear` `/resume` `/quit`
+
+## The three switches
+
+**Mode** decides what the agent may touch.
+
+- **Act** — the full tool set; it can change your project.
+- **Plan** — read-only. Write tools are not merely blocked, they are never shown
+  to the model, so you get a plan rather than a thwarted attempt to edit.
+- **Chat** — no tools at all.
+
+**Loop** decides whether it keeps going. On, the agent iterates until the task is
+done or a guard trips (steps, wall clock, spend). Off, it answers once.
+
+**GW** is the model gateway. Disabled — the default — every request goes to the
+provider you picked, so what the status bar says is what answered. Enabled, it
+ranks healthy providers by cost, speed or quality and fails over when a call
+breaks. A stream that has already produced output is never retried elsewhere:
+duplicating half an answer is worse than reporting the failure.
+
+## Reflex — a two-speed brain
+
+Most agents remember what you *tell* them. Comodor learns from what you *fix*.
+
+**Reflex is the fast lane.** Deterministic, model-free, sub-millisecond, always
+on. It reads five signals, all of them free because you produce them just by
+working:
+
+| signal | what it means |
+|---|---|
+| you rewrite a file the agent wrote | the diff *is* the preference — quotes, indentation, annotations, verbosity |
+| you `/undo` a change | an outright rejection |
+| you deny a permission | one command this user does not want run |
+| you ask the same thing twice | the answer missed |
+| a tool fails the same way twice | a pitfall in this environment, verified |
+
+Each becomes a **rule** with its evidence attached — not "I think you prefer
+single quotes" but `31 of 34 literals` — and how much evidence a rule needs
+depends on where it came from. Watching your codebase is weak proof, so it takes
+four agreeing observations. You editing the agent's output is a deliberate
+statement, so it takes two. Telling it outright takes one.
+
+Detection runs at the *start* of a turn, not the end. That is what makes the
+correction land immediately rather than a task later.
+
+**Reflection is the slow lane** — the original LLM pass that distils prose
+lessons from an episode. It still runs, in the background, and it is now
+optional. Switch it off, work offline, use a cheap model: Reflex keeps learning
+either way, because it never needed a model at all.
+
+Everything is inspectable and reversible:
+
+```
+/rules              browse rules with their evidence; pin, disable or drop one
+/rules teach Never add comments unless asked.
+/rules export       writes .comodor/house-rules.md for the team to commit
+/memory             the distilled lessons, same controls
+/teach  /good  /bad
+```
+
+## Proof, not claims: `/progress`
+
+"Gets better over time" is what every tool says. Comodor shows the numbers.
+
+```
+◈ Steps per task down 40% since the first tasks in this project.
+
+metric                trend                            now  vs first
+Steps per task        ▇██▇▇▆▇▅▅▅▅▆▄▅▄▅▄▄▂▄▂▁▂▂▂▁▁▁▁▁   5.3      ↓40%
+Corrections per task  ████▆▇▆█▆▆▆▇▆▆▅▃▃▅▆▆▅▃▆▃▆▃▂▁▁▃   0.9      ↓65%
+Approvals asked       █▇▇▇▇▇▇▇▇▇▅▅▅▅▅▅▅▅▅▅▃▃▃▃▃▃▃▃▃▁   0.8      ↓73%
+Tokens per task       █▇████▇▇▆▆▆▆▆▆▅▅▄▄▅▃▃▄▄▃▂▂▂▂▂▁  6.4K      ↓29%
+First-try success     ██▁███████████████████████████  100%      ↑8pp
+
+brain  7 rules · 23 lessons · 70 corrections learned from
+history  40 tasks over 2 days
+```
+
+The panel is built to be honest, which is what makes it worth showing: with too
+little history it says so, a metric that has not moved is reported as unchanged,
+a rate moves in percentage points rather than as a percentage of a percentage,
+and a fall from 0.4 to 0 is never allowed to headline as "down 100%".
+
+## Speed
+
+Memory sits between pressing Enter and the first token, so it is measured and
+budgeted. Against a deliberately worst-case corpus on a normal laptop:
+
+| operation | before | now |
+|---|---|---|
+| recall, 3,000 lessons | 2.0 ms | 0.38 ms |
+| recall, 20,000 lessons | — | **0.38 ms** (flat) |
+| deduplication, 3,000 lessons | 22 ms | 0.25 ms |
+| pinned lookup, 20,000 lessons | 8.9 ms | 0.10 ms |
+| recording reinforcement | 0.04 ms | 0.001 ms |
+
+Three things get it there. A **RAM mirror** holds every lesson with its tokens
+pre-computed and an inverted index over them, so a lookup touches only the
+documents sharing a word with the query — and the candidate set is capped, which
+is why the cost stops growing with the corpus. A **background writer** batches
+commits so nothing user-facing ever waits on the disk. And **speculative recall**
+runs the whole ranking while you are still typing, so on the turn itself it
+costs nothing at all.
+
+`tests/test_performance.py` enforces these as ceilings. A change that makes
+memory slow fails the suite.
+
+## Safety
+
+- **Risk tiers.** Reads never prompt. Writes show a coloured diff and ask.
+  Commands and network calls always ask.
+- **Checkpoints.** Files are snapshotted before any change; `/undo` restores them.
+- **A deny list** no prompt can talk past, for the handful of commands that are
+  never acceptable.
+- **Workspace confinement.** Writes outside the project are refused by default.
+- **Redaction.** API keys and tokens are stripped from logs, transcripts and
+  exports.
+- `--yes` exists for CI. Headless runs refuse to change anything without it.
+
+## Any terminal, any size
+
+The layout is recomputed every frame from the terminal size, so resizing just
+works.
+
+| Width | Layout |
+|---|---|
+| `< 60` | one column; sidebar on `F2` |
+| `60–99` | narrow sidebar, compact status |
+| `100–139` | the reference design |
+| `≥ 140` | wide sidebar, roomier transcript |
+
+Below 40×12 it says so plainly rather than drawing a corrupted screen. `--ascii`
+drops box-drawing glyphs for terminals that cannot render them, and a monochrome
+terminal gets a monochrome theme automatically.
+
+## Layout of the code
+
+```
+src/comodor/
+├─ net/         zero-dependency HTTP client + SSE reader
+├─ providers/   OpenAI-compatible, Anthropic, offline fake, and the gateway
+├─ agent/       the reason/act loop, context budgeting, prompts
+├─ tools/       files, search, shell, python, web, task list
+├─ safety/      permissions, checkpoints, redaction
+├─ learning/    the brain: hot index, async writer, signals, rules, progress
+├─ session/     persistence and export
+└─ ui/          layout, theme, widgets, raw input, the app loop
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+comodor preview 120x34            # render one frame at a fixed size
+comodor preview 60x20 --svg out.svg
+```
+
+The test suite runs the whole agent against a scripted provider, so there is no
+network and no spend, and renders the interface at a range of sizes to prove the
+responsive layout holds.
+
+## Licence
+
+MIT.