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.
