Prax CLI
Python runtime for agent work: task boundaries, independent verification of results and a saved handoff between sessions
- 272 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The Claude or Codex worker edits repository files and runs tests, and the guards notice drift at boundaries but cannot roll back side effects
- The Claude Code installer changes the user directory `~/.claude`, where your settings live
Install
- Works in
Manual install
python3 -m venv .venv && .venv/bin/python -m pip install -e .From a clone made with `git clone https://github.com/ChanningLua/prax-agent.git`. Check without model calls: `.venv/bin/prax --version`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The Claude or Codex worker edits repository files and runs tests, and the guards notice drift at boundaries but cannot roll back side effects
- The Claude Code installer changes the user directory `~/.claude`, where your settings live
This is third-party code. Review the repository files before installing.
What it does
Prax runs an agent's work inside set boundaries and leaves evidence of the result. The `prax shift` command takes a frozen task from `.prax/task.json`: a goal, the editable repositories and branches, an acceptance check and a total attempt budget. If the check already passes, no worker is needed. Otherwise Claude or Codex makes a limited number of repair attempts and an independent verifier decides whether the work is accepted. `prax shift plan` validates the contract and the repository state but starts neither tests nor a worker. Results land in `.prax/harness-runs/<task-id>/`. The `verification` mode runs a project's tests once through a bridge and separates passed, failed, blocked and not-executed cases. Beyond that, Prax ships its own terminal agent with `prax prompt` and `prax repl`, with support for skills, subagents and MCP tools. For Claude Code the package brings skills, commands, rules and hooks, and for Codex it installs the project-scoped `prax-shift` skill. There are recipes for articles, research and release notes.
Who it is for. Developers who hand an agent a bounded repository task and want the result with independent acceptance, a journal and an attempt budget.
Good fit when
- A bug in the empty-input parser should go to an agent inside one folder with frozen tests and a three-attempt limit
- You need to run end-to-end tests once and get separate accounting of passed, failed and blocked cases
- Work has to pause and resume later without losing the budget or accumulated state
- Claude or Codex should be the worker while acceptance goes to the project's own independent test
Not a fit when
- You need an operating-system sandbox: Prax does not create one, its repository guards notice drift at boundaries but cannot undo side effects
- The task is open-ended with no acceptance check: the contract requires a test or another verifiable criterion
- You want a fully autonomous endless backlog: budgets and stops are explicit, and a schedule only continues a known task
- You need Windows: the instructions target macOS and Linux
Example request
Use Prax Shift to fix the empty-input parser bug: edit only the parser folder, keep tests frozen, three attempts, no commits, show the plan firstLimitations
- The README describes the `main` branch, a published package may lag, so the documented capabilities need a source checkout.
- It needs Python 3.10 on macOS or Linux. The Codex install probe works only on macOS and depends on the Codex CLI version.
- The Claude Code installer changes the user directory `~/.claude`, unlike the project-scoped Codex install.
- The author treats tests and adapters as trusted executable code and does not call the repository guards a sandbox.
- The last commit is dated September 2026.
How to disable. For the project-scoped Codex install, delete `.codex/skills/prax-shift/SKILL.md` and `.prax/codex-install.json`, and you can erase the `.prax/venv` directory entirely. For Claude Code, revert the changes the installer made in `~/.claude` and delete the repository clone.
FAQ
How do I install Prax?
Clone the repository and run `python -m pip install -e .` in a virtual environment, then check `.venv/bin/prax --version`. It needs Python 3.10 on macOS or Linux, and Node.js is not required.
What does prax shift plan do?
It validates the task contract and the repository source but starts no tests, worker or scheduler. That lets you see what Prax intends to do before you approve a run.
Which agents can act as workers?
Claude and Codex, chosen in the repository profile through the `worker` field. Codex defaults to `workspace-write` and Claude to `dontAsk`, and their isolation is not equivalent.
How does verification mode differ from shift?
`verification` runs tests once with no worker, retries or resume. `shift` runs a repair loop around a code task with a check after each attempt.
Does Prax protect against dangerous commands?
No, it is not an operating-system sandbox. Repository guards detect drift at task boundaries, while tests and adapters remain trusted executable code.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI, hooks and skills for long Claude, Codex and Pi work: the issue and PR own the task and review gets a PR with checks
Over twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
Tasks, docs, specs and decisions live as markdown files in your repository, and the agent reads them through the CLI and MCP
A CLI that gives six coding agents project context, over 80 skills, verification and resumable tasks across sessions
Codely team skills that run agent work in phases: a plan in a file or GitHub issues, review after each phase and a clean commit
A tool and skill that let Claude Code hand tasks to Claude, Codex or OpenCode subagents in separate Git worktrees
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Prax (this card) | no | 272 | |
| repo-harness: a workflow for Claude, Codex and Pi agents in a repository | no | 435 | runs a similar check loop but without a frozen task contract and attempt budget |
| Ralph TUI | no | 2,461 | drives an agent through a task list in the terminal without independent acceptance |
README in short
The README presents agent work with explicit boundaries, repeatable workflows and evidence-backed results. It explains the three architecture layers, installation, entry points for the native agent, Codex and Claude Code, the Prax Shift commands and verification mode, and ends with known limits.