comodor 0.2.0__tar.gz → 0.2.2__tar.gz

{comodor-0.2.0 → comodor-0.2.2}/.gitignore

@@ -29,3 +29,12 @@ next-env.d.ts
 .env*.local
 npm-debug.log*
 dist/
+
+TODO
+
+# Written by the build from the git tag.
+src/comodor/_version.py
+
+# uv writes this when it resolves an environment here. Comodor is a library
+# as well as an application; a lock file would pin its users, not just us.
+uv.lock

comodor-0.2.2/PKG-INFO

@@ -0,0 +1,435 @@
+Metadata-Version: 2.5
+Name: comodor
+Version: 0.2.2
+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
+Project-URL: Issues, https://github.com/ifekri/Comodor/issues
+Project-URL: Changelog, https://github.com/ifekri/Comodor/blob/main/CHANGELOG.md
+Author-email: MMDRZA <mohammadreza.fekri.mojdehi@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,coding-assistant,llm,rich,terminal,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: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Comodor
+
+**A coding agent that lives in your terminal — and learns the way you correct it.**
+
+[comodor.ai](https://comodor.ai) · [Install](#install) · [What it can do](#what-it-can-do)
+
+---
+
+## What this is
+
+Comodor is a program you run in your terminal and talk to in plain language.
+You describe a job — *fix the failing test*, *add a health endpoint*, *work out
+why the deploy broke* — and it does the work: reads your files, writes changes,
+runs your tests, searches the web, and keeps going until the job is done or it
+needs you.
+
+It asks before it changes anything, shows you exactly what it is about to do,
+and can undo it.
+
+What makes it different from every other tool of this kind is what happens
+afterwards. **When you fix something it wrote, it notices, and it does not make
+that mistake again.** Not because you configured it. Because it watched.
+
+```
+› create defaults.py with 6 string constants
+⚙ write src/defaults.py — 6 constants
+
+  … you open the file and change "30s" to '30s' …
+
+› now add the timeout constants
+◈ learned: Use single quotes for string literals.   (31 of 34 literals)
+⚙ write src/defaults.py — '30s', '5m'
+```
+
+That is a real transcript. 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 · skill: review                 │
+│ ● 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                                  │
+└────────────────────────┘ └──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Install
+
+**macOS and Linux**
+
+```bash
+curl -fsSL https://comodor.ai/install.sh | sh
+```
+
+**Windows**
+
+```powershell
+irm https://comodor.ai/install.ps1 | iex
+```
+
+**The installer finishes the job.** It finds a Python or fetches one, builds an
+isolated environment so nothing on your machine is disturbed, puts `comodor` on
+your PATH, and runs it once to prove it worked. You do not need Python
+installed, and you will not be handed a wall of packaging errors.
+
+Already have a package manager? Any of these work:
+
+```bash
+uv tool install comodor
+pipx install comodor
+pip install comodor
+```
+
+Then type `comodor`.
+
+---
+
+## First run
+
+Four questions, once. Nothing to create beforehand — no config file, no
+environment variable, no documentation to read first.
+
+```
+ 1/4  Which model provider?      18 to choose from, numbered
+ 2/4  API key                    masked, with a link to the page that issues one
+ 3/4  Which model?               read live from the provider you just chose
+ 4/4  How much should it ask?    ask first · writes allowed · full autonomy
+```
+
+You are not asked again. Change your mind later with `comodor setup`.
+
+**No API key?** `comodor --demo` runs the whole interface offline — every
+panel, every command, no account required.
+
+---
+
+## What it can do
+
+### It learns from your corrections
+
+Most assistants remember what you *tell* them. Comodor learns from what you
+*fix*. It reads five things, all of which you produce just by working:
+
+| what you did | what it means |
+|---|---|
+| you rewrote a file it wrote | the diff is the preference — quotes, indentation, verbosity |
+| you pressed `/undo` | an outright rejection |
+| you refused a command | one thing you do not want run |
+| you asked the same thing twice | the answer missed |
+| a tool failed the same way twice | a real pitfall in this environment |
+
+Each becomes a **rule with its evidence attached** — not *"I think you prefer
+single quotes"* but `31 of 34 literals`. How much evidence a rule needs depends
+on where it came from: four agreeing observations to trust your codebase, two
+for an edit you made, one for something you said outright.
+
+It happens with **no extra model call and no waiting**, and it is announced
+rather than silent. `/rules` shows every rule, what convinced it, and lets you
+drop any of them.
+
+### It follows procedures you write down
+
+A **skill** is a plain Markdown file describing how you want a kind of work
+done — your review checklist, your commit conventions, the deploy steps nobody
+remembers.
+
+```markdown
+---
+name: review
+description: Review a change for correctness before it is committed
+---
+
+Read the whole change before saying anything about it.
+Report only what would block a merge.
+```
+
+Drop it in `~/.comodor/skills/` for everywhere, or `.comodor/skills/` to commit
+it with the project so your whole team gets it. Comodor loads one only when the
+request calls for it, so twenty skills cost no more than one.
+
+It uses the [Agent Skills](https://agentskills.io) open format, so a skill
+written for another tool works here, and yours work there.
+
+**It also writes them for you.** When it has solved the same shape of problem
+three times, `/skills draft` offers the procedure back as a finished file — with
+the evidence — and writes nothing until you say yes.
+
+### It remembers every session
+
+Everything you have ever asked is searchable.
+
+```
+/search cursor pagination
+
+  you · 12 Apr · 20260412-090000
+  > add cursor pagination to the results endpoint
+```
+
+The agent searches it too, on its own, when you refer to earlier work — *"like
+we did last time"*, *"that bug from last week"*.
+
+### It connects to other tools
+
+Comodor speaks the [Model Context Protocol](https://modelcontextprotocol.io),
+so it can use capabilities it does not implement itself: a browser, a database,
+your issue tracker.
+
+```bash
+comodor mcp catalogue                      # twelve servers, ready to go
+comodor mcp add filesystem --path ~/work
+comodor mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=…
+comodor mcp custom my-server uvx my-package   # anything else
+```
+
+| | |
+|---|---|
+| **Files and code** | Filesystem · Git · GitHub |
+| **Data** | SQLite · PostgreSQL |
+| **The web** | Fetch · Brave Search · Browser (Puppeteer) |
+| **Other** | Memory · Sequential thinking · Slack · Time |
+
+Each entry says **what it can reach** before you enable it. Nothing starts
+until it is used.
+
+### It fixes itself
+
+```
+$ comodor doctor
+
+Checks
+  ok    provider        Anthropic · claude-sonnet-4-5
+  warn  session search  the index is corrupt
+              → delete it — it is a cache built from the transcripts
+  ok    mcp servers     2 enabled and reachable
+
+1 of these can be repaired automatically: comodor doctor --fix
+```
+
+`--fix` repairs what it can rebuild and **refuses what it cannot**. A corrupt
+cache gets deleted. A corrupt config is reported and left exactly as it was,
+because it holds your API key — the one thing on your machine that cannot be
+regenerated.
+
+### It leaves when you ask it to
+
+```
+$ comodor uninstall
+
+Your data
+  everything it has learned and everything you told it   14 MB
+    ~/.comodor
+    settings and your API key · learned rules and lessons · 62 sessions · 4 skills
+
+In your projects
+  api-server                                            1.2 MB
+    ~/work/api-server/.comodor
+
+The program
+  the isolated environment                               112 MB
+    ~/.local/share/comodor
+
+Your shell
+  the PATH line the installer added
+    ~/.bashrc
+
+127 MB across 5 places. None of it can be undone.
+
+Type uninstall to confirm, or anything else to stop.
+```
+
+It shows the list before it touches anything, and `--dry-run` stops there. What
+goes is the data directory, the `.comodor` folder in every project it was used
+in, the environment the installer built, the `comodor` command, and the line
+the installer put in your shell profile. Afterwards there is nothing of it left
+on the machine.
+
+It knows which projects to clean because every session records where it ran —
+not by searching your disk. Three things it will not do: touch a source
+checkout, take a directory off your PATH that other programs are still using,
+or claim to have deleted a file the operating system would not let go of.
+
+### It can prove it is improving
+
+Every tool claims to get better over time. 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%
+```
+
+The panel is built to under-claim: with too little history it says so, and a
+fall from 0.4 to 0 is never allowed to headline as "down 100%".
+
+---
+
+## You stay in control
+
+- **Reads never interrupt you. Writes show a coloured diff and ask. Commands
+  and network calls always ask.**
+- **Checkpoints.** Every file is snapshotted before it changes; `/undo`
+  restores it.
+- **A deny list no prompt can talk past**, for commands that are never
+  acceptable — whatever the model, or you, may ask for in the moment.
+- **It stays inside your project.** Writes outside it are refused by default.
+- **Your keys never appear** in logs, transcripts or exports.
+
+Three switches decide how much rope it gets:
+
+| | |
+|---|---|
+| **Act** | the full tool set — it can change your project |
+| **Plan** | read-only, and the write tools are hidden from the model entirely, so you get a plan rather than a thwarted attempt to edit |
+| **Chat** | no tools at all |
+
+**Loop** decides whether it keeps going by itself until the job is done or a
+budget trips — steps, wall clock, or money. **Gateway** can spread work across
+providers and fail over when one breaks.
+
+---
+
+## Bring your own model
+
+| | |
+|---|---|
+| **Hosted** | OpenRouter · Anthropic · OpenAI · Google Gemini · DeepSeek · xAI · Mistral · Groq · Cerebras · Moonshot · Z.AI · Qwen · Together · Fireworks · Xiaomi MiMo |
+| **On your machine** | Ollama · LM Studio — no key, no cost, no network |
+| **Anything else** | any OpenAI-compatible endpoint |
+
+Each knows its own endpoint, model list and where to get a key, so choosing one
+is a single number. Switch any time with `/provider`, or per run:
+
+```bash
+comodor --provider groq --model llama-3.3-70b-versatile
+```
+
+---
+
+## Everyday 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, for pipelines
+comodor doctor                              # check everything; --fix repairs it
+comodor uninstall                           # remove it completely; --dry-run first
+```
+
+| Key | |
+|---|---|
+| `Enter` | send · `Ctrl+J` for a newline |
+| `Esc` | stop the agent |
+| `F1` … `F5` | help · sidebar · mode · loop · gateway |
+| `Ctrl+O` | attach a file |
+| `Ctrl+C` | stop; twice to quit |
+
+`!command` runs a shell command directly. `@path` attaches a file.
+
+**Commands** — `/help` `/model` `/provider` `/mode` `/loop` `/rules`
+`/progress` `/memory` `/skills` `/search` `/mcp` `/undo` `/cost` `/export`
+`/settings` `/resume` `/quit`
+
+---
+
+## Configuration
+
+One JSON file, written for you and safe to edit by hand.
+
+| | |
+|---|---|
+| Linux and macOS | `~/.comodor/config.json` |
+| Windows | `%APPDATA%\Comodor\config.json` |
+
+It is written atomically and, on Unix, readable only by you, because it holds
+your key. A `.comodor/config.json` inside a repository is merged over your
+personal one, so a team can pin settings without sharing secrets. Provider
+environment variables still take precedence, which keeps CI working with no
+file at all.
+
+---
+
+## Any terminal, any size
+
+The layout is recomputed every frame, so resizing just works — from a
+40-column SSH window to an ultrawide monitor. Below the floor it says so
+plainly rather than drawing a corrupted screen, `--ascii` covers terminals
+without box-drawing glyphs, and a monochrome terminal gets a monochrome theme
+automatically.
+
+Recall — the wait between pressing Enter and the first token — is **0.38 ms and
+stays there** whether the agent has learned three thousand things or twenty
+thousand. That is measured, not asserted: `tests/test_performance.py` enforces
+it as a ceiling, so a change that makes it slow fails the build.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ifekri/Comodor && cd Comodor
+python -m venv .venv
+.venv/Scripts/activate        # Windows;  source .venv/bin/activate elsewhere
+pip install -e ".[dev]"
+pytest -q                     # 472 tests, no network, no spend
+```
+
+```
+src/comodor/
+├─ agent/       the reason/act loop, context budgeting, prompts
+├─ learning/    the brain: rules, lessons, signals, progress
+├─ skills/      authored skills: the open format, matching, drafts
+├─ mcp/         the Model Context Protocol client and server catalogue
+├─ providers/   every backend, and the gateway between them
+├─ safety/      permissions, checkpoints, redaction
+├─ session/     persistence, export, full-text search
+├─ tools/       files, search, shell, python, web, task list
+└─ ui/          layout, theme, widgets, raw input, the app loop
+```
+
+The suite runs the whole agent against a scripted provider — no network, no
+spend — and renders the interface at a range of terminal sizes to prove the
+responsive layout holds.
+
+```bash
+comodor preview 120x34            # render one frame at a fixed size
+```
+
+---
+
+## Contributing
+
+Bug reports welcome — please include `comodor doctor`, which prints everything
+we would otherwise have to ask for. [CONTRIBUTING.md](CONTRIBUTING.md) covers
+the setup. Security issues go [here](SECURITY.md), privately.
+[CHANGELOG.md](CHANGELOG.md) records what changed in each release.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).