First session

A full walkthrough of one realistic Cogtrix session. Shows tool calls, confirmations, memory, and how the agent chains steps on its own.

The task

You want to refactor a Python module, run its tests, and commit the result.

Starting up

uv run python cogtrix.py

Cogtrix prints a banner with the active provider/model, the loaded tools count, and your current session ID. The prompt is You>.

Turn 1 — read the code

You> Show me the function signatures in src/utils/parser.py.

Cogtrix> read_file("src/utils/parser.py", lines="1-200")
         Found 8 top-level functions:
           parse_args(argv: list[str]) -> Namespace
           load_config(path: Path) -> Config
           …

read_file is auto-approved (read-only tools don’t require confirmation). The model now has the contents in its working memory — subsequent turns can reference them by name.

Turn 2 — refactor with a confirmation prompt

You> Extract the YAML parsing logic from load_config into a separate helper.

Cogtrix> patch_file("src/utils/parser.py", old=..., new=...)
         ⚠️  Tool 'patch_file' requires confirmation. Apply? [y/n/a/d/f/c]
You> y
         Patched src/utils/parser.py: 1 insertion, 6 modifications.

The confirmation prompt shows the exact diff before applying. Responses:

• y — approve this single call
• n — deny it
• a — auto-approve patch_file for the rest of this session
• d — disable patch_file for the rest of this session
• f — forbid all further tool calls this turn
• c — cancel the current workflow

Turn 3 — run the tests

You> Run the parser tests.

Cogtrix> execute_shell_command("uv run pytest tests/test_parser.py -v")
         ⚠️  Tool 'execute_shell_command' requires confirmation. Apply? [y/n/a/d/f/c]
You> y
         12 passed in 0.34s.

Turn 4 — commit

You> Commit with a descriptive message.

Cogtrix> git_add("src/utils/parser.py")
         git_commit("refactor(parser): extract YAML parsing into _load_yaml helper")
         Committed 1 file. Hash: a3f29b1.

git_commit is also a [confirm] tool. You approve it the same way.

What just happened

In four turns, Cogtrix:

1. Read your code.
2. Modified it with your approval.
3. Ran your test suite.
4. Committed the change.

No copy-pasting between a chat window and a terminal. Every action was visible, asked first, and recorded in the session’s history.

Memory between turns

If you exit and resume the same session (-s <session-id>), Cogtrix restores the conversation — every tool call, every patch, every test result — and can answer “what did we change earlier?” without re-reading the files.

→ Memory modes — when to switch from conversation to code or reasoning mode.