comodor 0.8.8__tar.gz → 0.9.0__tar.gz

comodor-0.9.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: comodor
+Version: 0.9.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
+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'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Comodor
+
+**A coding agent that lives in your terminal — and learns the way you correct it.**
+
+[![PyPI](https://img.shields.io/pypi/v/comodor?label=pypi&color=c4441e)](https://pypi.org/project/comodor/)
+[![Python](https://img.shields.io/pypi/pyversions/comodor)](https://pypi.org/project/comodor/)
+[![CI](https://github.com/ifekri/Comodor/actions/workflows/ci.yml/badge.svg)](https://github.com/ifekri/Comodor/actions/workflows/ci.yml)
+[![Licence](https://img.shields.io/pypi/l/comodor?color=555)](LICENSE)
+
+**[Documentation](docs/README.md)** · [comodor.ai](https://comodor.ai) · [Changelog](CHANGELOG.md)
+
+---
+
+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
+
+```bash
+uv tool install comodor      # or: pipx install comodor, or: pip install comodor
+comodor
+```
+
+Python 3.11 or newer. It asks five questions the first time and never asks
+again.
+
+No key yet? `comodor --demo` runs the whole interface offline. Or choose
+**Ollama** in the setup and pay nothing, ever.
+
+Already use OpenClaw or Hermes? The first screen offers to bring your keys and
+skills across. [How that works](docs/migrating.md).
+
+---
+
+## What it can do
+
+| | |
+|---|---|
+| **Learn from your corrections** | Edit what it wrote, or say so, and the next answer follows. `/progress` shows whether that is actually working — falling correction rates, not a claim. [More](docs/learning.md) |
+| **Ask before it acts** | Reading is silent, writing shows a diff, commands ask. Every write is checkpointed; `/undo` puts it back. [More](docs/safety.md) |
+| **Use a real browser** | One that runs JavaScript, keeps cookies and can log in — not a page fetcher. [More](docs/browser.md) |
+| **Use your screen** | Mouse and keyboard, in any application, with a halo on screen showing where it is about to click. Windows so far. [More](docs/computer.md) |
+| **Follow your procedures** | Write a skill once; it loads it when the work matches. [More](docs/skills.md) |
+| **Run anywhere** | Terminal, browser, or a container. [Web](docs/web.md) · [Docker](docs/docker.md) |
+| **Work with any model** | Seventeen providers, or anything with an OpenAI-compatible URL. Including ones on your own machine. [More](docs/models.md) |
+| **Cost less than it should** | 86% of input tokens served from cache, measured. [More](docs/cost.md) |
+
+**One dependency.** The HTTP client, the SSE reader, the WebSocket for the
+browser, the PNG encoder for screenshots — all part of the package. Installing
+Comodor pulls in `rich` and nothing else.
+
+---
+
+## Everyday use
+
+```bash
+comodor                                    # the interface
+comodor run "fix the failing test" --yes   # one task, no interface
+comodor web                                # from a browser
+comodor doctor                             # is everything alright?
+comodor help                               # a written help page, not a flag dump
+```
+
+```
+/help      every command          /undo      restore the last change
+/mode      act · plan · chat      /progress  proof it is improving
+/cost      tokens and spend       /computer  let it use your screen
+Esc        stop it                F3         cycle mode
+```
+
+---
+
+## Documentation
+
+**[docs/README.md](docs/README.md)** — everything, organised by what you are
+trying to do.
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, choose a model, first task |
+| [The interface](docs/interface.md) | Panels, keys, and all 27 commands |
+| [From the terminal](docs/cli.md) | Every command and flag |
+| [What the agent can do](docs/tools.md) | The 13 tools, and when it uses each |
+| [Safety and permissions](docs/safety.md) | What it can do, and what it never does |
+| [How it learns](docs/learning.md) | Corrections, lessons, and the evidence |
+| [Using your screen](docs/computer.md) | Mouse and keyboard, watched |
+| [Configuration](docs/configuration.md) | Every setting, and what wins |
+| [Cost](docs/cost.md) | Caching, budgets, paying less |
+| [Troubleshooting](docs/troubleshooting.md) | When something is wrong |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ifekri/Comodor.git
+cd Comodor
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+```
+
+Both must pass before anything is pushed, on Linux and on Windows.
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+Security: [SECURITY.md](SECURITY.md) — please do not open a public issue.

comodor-0.9.0/README.md

@@ -0,0 +1,150 @@
+# Comodor
+
+**A coding agent that lives in your terminal — and learns the way you correct it.**
+
+[![PyPI](https://img.shields.io/pypi/v/comodor?label=pypi&color=c4441e)](https://pypi.org/project/comodor/)
+[![Python](https://img.shields.io/pypi/pyversions/comodor)](https://pypi.org/project/comodor/)
+[![CI](https://github.com/ifekri/Comodor/actions/workflows/ci.yml/badge.svg)](https://github.com/ifekri/Comodor/actions/workflows/ci.yml)
+[![Licence](https://img.shields.io/pypi/l/comodor?color=555)](LICENSE)
+
+**[Documentation](docs/README.md)** · [comodor.ai](https://comodor.ai) · [Changelog](CHANGELOG.md)
+
+---
+
+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
+
+```bash
+uv tool install comodor      # or: pipx install comodor, or: pip install comodor
+comodor
+```
+
+Python 3.11 or newer. It asks five questions the first time and never asks
+again.
+
+No key yet? `comodor --demo` runs the whole interface offline. Or choose
+**Ollama** in the setup and pay nothing, ever.
+
+Already use OpenClaw or Hermes? The first screen offers to bring your keys and
+skills across. [How that works](docs/migrating.md).
+
+---
+
+## What it can do
+
+| | |
+|---|---|
+| **Learn from your corrections** | Edit what it wrote, or say so, and the next answer follows. `/progress` shows whether that is actually working — falling correction rates, not a claim. [More](docs/learning.md) |
+| **Ask before it acts** | Reading is silent, writing shows a diff, commands ask. Every write is checkpointed; `/undo` puts it back. [More](docs/safety.md) |
+| **Use a real browser** | One that runs JavaScript, keeps cookies and can log in — not a page fetcher. [More](docs/browser.md) |
+| **Use your screen** | Mouse and keyboard, in any application, with a halo on screen showing where it is about to click. Windows so far. [More](docs/computer.md) |
+| **Follow your procedures** | Write a skill once; it loads it when the work matches. [More](docs/skills.md) |
+| **Run anywhere** | Terminal, browser, or a container. [Web](docs/web.md) · [Docker](docs/docker.md) |
+| **Work with any model** | Seventeen providers, or anything with an OpenAI-compatible URL. Including ones on your own machine. [More](docs/models.md) |
+| **Cost less than it should** | 86% of input tokens served from cache, measured. [More](docs/cost.md) |
+
+**One dependency.** The HTTP client, the SSE reader, the WebSocket for the
+browser, the PNG encoder for screenshots — all part of the package. Installing
+Comodor pulls in `rich` and nothing else.
+
+---
+
+## Everyday use
+
+```bash
+comodor                                    # the interface
+comodor run "fix the failing test" --yes   # one task, no interface
+comodor web                                # from a browser
+comodor doctor                             # is everything alright?
+comodor help                               # a written help page, not a flag dump
+```
+
+```
+/help      every command          /undo      restore the last change
+/mode      act · plan · chat      /progress  proof it is improving
+/cost      tokens and spend       /computer  let it use your screen
+Esc        stop it                F3         cycle mode
+```
+
+---
+
+## Documentation
+
+**[docs/README.md](docs/README.md)** — everything, organised by what you are
+trying to do.
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, choose a model, first task |
+| [The interface](docs/interface.md) | Panels, keys, and all 27 commands |
+| [From the terminal](docs/cli.md) | Every command and flag |
+| [What the agent can do](docs/tools.md) | The 13 tools, and when it uses each |
+| [Safety and permissions](docs/safety.md) | What it can do, and what it never does |
+| [How it learns](docs/learning.md) | Corrections, lessons, and the evidence |
+| [Using your screen](docs/computer.md) | Mouse and keyboard, watched |
+| [Configuration](docs/configuration.md) | Every setting, and what wins |
+| [Cost](docs/cost.md) | Caching, budgets, paying less |
+| [Troubleshooting](docs/troubleshooting.md) | When something is wrong |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ifekri/Comodor.git
+cd Comodor
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+```
+
+Both must pass before anything is pushed, on Linux and on Windows.
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+Security: [SECURITY.md](SECURITY.md) — please do not open a public issue.

comodor-0.9.0/docs/README.md

@@ -0,0 +1,103 @@
+# Comodor documentation
+
+A terminal coding agent that learns the way you correct it.
+
+New here? **[Getting started](getting-started.md)** takes about five minutes and
+ends with the agent doing something useful.
+
+---
+
+## By what you are trying to do
+
+### Get going
+
+| | |
+|---|---|
+| [Getting started](getting-started.md) | Install, choose a model, first task |
+| [Coming from another agent](migrating.md) | Bring keys and skills from OpenClaw or Hermes |
+| [Choosing a model](models.md) | Which provider, which model, what it costs |
+
+### Use it
+
+| | |
+|---|---|
+| [The interface](interface.md) | Panels, keys, modes, and all 27 commands |
+| [From the terminal](cli.md) | Every command and flag, with examples |
+| [What the agent can do](tools.md) | The 13 tools it has, and when it uses each |
+| [Skills](skills.md) | Procedures you write once and it follows |
+
+### Let it reach further
+
+| | |
+|---|---|
+| [The real browser](browser.md) | A browser that runs JavaScript and can log in |
+| [Using your screen](computer.md) | Mouse and keyboard, in any application |
+| [From a browser](web.md) | The web interface, locally or on a server |
+| [In Docker](docker.md) | One command, in a container |
+| [MCP servers](mcp.md) | Tools from the Model Context Protocol |
+
+### Understand it
+
+| | |
+|---|---|
+| [How it learns](learning.md) | Corrections, lessons, rules, and the proof |
+| [Safety and permissions](safety.md) | What it can do, what it asks, what it never does |
+| [Cost](cost.md) | Caching, budgets, and paying less for the same work |
+| [Configuration](configuration.md) | Every setting, where files live, what wins |
+
+### When something is wrong
+
+| | |
+|---|---|
+| [Troubleshooting](troubleshooting.md) | `doctor`, common problems, and how to report one |
+
+---
+
+## The shortest possible version
+
+```bash
+pip install comodor      # or: uv tool install comodor
+comodor                  # it asks a few questions, once
+```
+
+Then type what you want. Correct it when it is wrong — edit the file, or just
+say so — and it learns. `/progress` shows you whether that is actually working.
+
+```bash
+comodor run "fix the failing test in tests/test_parser.py"   # one task, no interface
+comodor web                                                  # from a browser
+comodor doctor                                               # is everything alright?
+comodor help                                                 # the written help page
+```
+
+## What makes it different
+
+**It learns from corrections, not from praise.** Most agents forget the moment
+a session ends. Comodor watches what you change about its output and turns that
+into a lesson with a confidence that rises when it holds and falls when it does
+not. [How it learns](learning.md) explains the mechanism; `/progress` shows the
+evidence.
+
+**It asks before it acts, and everything is reversible.** Reading is silent.
+Writing asks. Running a command asks louder. Every write is checkpointed, and
+`/undo` puts the last one back. [Safety and permissions](safety.md).
+
+**One dependency.** The HTTP client, the SSE reader, the WebSocket for the
+browser, the PNG encoder for screenshots — all part of the package. Installing
+Comodor pulls in `rich` and nothing else.
+
+**It can use a real browser and a real desktop.** Not a text fetcher: a browser
+that runs JavaScript and keeps cookies, and — on Windows — the mouse and
+keyboard, with a halo on screen showing you where it is about to click.
+[Browser](browser.md), [screen](computer.md).
+
+---
+
+## Also in the repository
+
+| | |
+|---|---|
+| [CHANGELOG](../CHANGELOG.md) | What changed, and why |
+| [CONTRIBUTING](../CONTRIBUTING.md) | Working on Comodor itself |
+| [SECURITY](../SECURITY.md) | Reporting something sensitive |
+| [RELEASING](../RELEASING.md) | How a release is cut |

{comodor-0.8.8 → comodor-0.9.0}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.8'
-__version_tuple__ = version_tuple = (0, 8, 8)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
 __commit_id__ = commit_id = None

{comodor-0.8.8 → comodor-0.9.0}/src/comodor/agent/context.py

@@ -136,6 +136,32 @@ class Conversation:
         self.compactions += 1
         return len(middle)
 
+    def forget_old_pictures(self, keep: int = 2) -> int:
+        """Drop all but the newest screenshots. Returns how many went.
+
+        A picture costs the same every turn it stays in the history, and a
+        screen from twenty clicks ago is not what is on the screen now. The
+        message is left in place with a note where the image was, so the model
+        can see that it looked and when, without paying to look again.
+
+        `keep` is small on purpose. Two is enough to compare "before" with
+        "after"; a third is a screen two actions old, which is history.
+        """
+        seen = 0
+        dropped = 0
+        for message in reversed(self.messages):
+            if not message.images:
+                continue
+            seen += 1
+            if seen <= keep:
+                continue
+            dropped += len(message.images)
+            message.images = []
+            note = "[the screenshot from this step is no longer in context]"
+            if note not in message.content:
+                message.content = (message.content + "\n" + note).strip()
+        return dropped
+
     # -- introspection ---------------------------------------------------- #
 
     def summary_line(self) -> str:

{comodor-0.8.8 → comodor-0.9.0}/src/comodor/agent/loop.py

@@ -318,6 +318,15 @@ class AgentLoop:
 
     def _maybe_compact(self, system_prompt: str, specs: list[ToolSpec]) -> None:
         agent = self.config.agent
+
+        # Before measuring anything. Screenshots are the largest thing in a
+        # desktop run's history and the fastest to go stale, and dropping them
+        # is exact and free - where compaction is a model call. Doing it first
+        # also means the measurement below is of what will actually be sent.
+        gone = self.conversation.forget_old_pictures(
+            getattr(agent, "keep_screenshots", 2))
+        if gone:
+            self._emit_usage(system_prompt, specs)
         limit = agent.context_limit or 128_000
         if not self.conversation.needs_compaction(limit, agent.compact_at,
                                                   system_prompt, specs):

{comodor-0.8.8 → comodor-0.9.0}/src/comodor/cli.py

@@ -35,7 +35,15 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="comodor",
         description="Comodor — a terminal coding agent that learns as it works.",
+        # argparse's own help is a list of flags. That answers "what arguments
+        # does this take" and not "what is this, and what do I do now", which
+        # is what somebody typing --help is asking. See `help.py`. Only the top
+        # level is taken over: for one subcommand, the list of its flags really
+        # is the answer.
+        add_help=False,
     )
+    parser.add_argument("-h", "--help", action="store_true", dest="want_help",
+                        help="this page, or `comodor help <topic>` for one part")
     parser.add_argument("--version", action="version", version=f"comodor {__version__}")
 
     parser.add_argument("--provider", help="provider to use (openrouter, anthropic, …)")
@@ -62,6 +70,11 @@ def build_parser() -> argparse.ArgumentParser:
                      help="approve file writes and commands automatically")
     run.add_argument("--max-steps", type=int, help="override the step limit")
 
+    written = sub.add_parser(
+        "help", help="what this is and how to use it, in full")
+    written.add_argument("topic", nargs="?", default="",
+                         help="one part of it, in more detail")
+
     sub.add_parser("setup", help="choose a provider and model, and save the answers")
     brought = sub.add_parser(
         "import", help="bring keys, model and skills over from another agent")
@@ -189,7 +202,7 @@ def run_headless(config: Config, args: argparse.Namespace) -> int:
     permissions.on_denied = memory.on_denied
     skills = load_skills(config)
     mcp = MCPManager(config.mcp.servers) if config.mcp.enabled else None
-    tools = ToolRegistry(skills=skills, mcp=mcp,
+    tools = ToolRegistry(skills=skills, mcp=mcp, config=config,
                          spawn=spawner(config, gateway, bus, skills=skills, mcp=mcp))
     agent = AgentLoop(config, gateway, tools, bus,
                       permissions, Conversation(), memory, skills=skills)
@@ -692,6 +705,15 @@ def run_import(config: Config, args: argparse.Namespace) -> int:
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
+
+    # Before the configuration is loaded: somebody who cannot get the program
+    # to start is exactly the person who needs the help page, and loading a
+    # broken config first would deny it to them.
+    if getattr(args, "want_help", False) or args.command == "help":
+        from .help import render
+
+        return render(topic=getattr(args, "topic", "") or "")
+
     config = apply_overrides(load_config(args.cwd), args)
 
     if args.command == "doctor":