Mobius

Mobius runs a coding agent against one objective until the agent reports completion and your project checks pass.

Mobius is a Python command-line tool. It works with Codex, Claude Code, Gemini CLI, and custom local commands. It does not provide an agent or model of its own.

Requirements

• Python 3.10 or later
• A supported coding-agent CLI installed and authenticated
• A project with one or more useful validation commands

Install

The PyPI distribution is named mobius-agent. The installed command is mobius.

Using pipx:

pipx install mobius-agent

Using uv:

uv tool install mobius-agent

Using pip in an active virtual environment:

python -m pip install mobius-agent

The package must be published to PyPI before these public install commands work. For local development, see Development.

Quick start

Run these commands from the project that the agent should modify:

mobius init
mobius doctor
mobius run "Fix the failing checkout tests"

mobius init creates mobius.config.json and adds .mobius/ to .gitignore. Review the generated validation command before starting a run.

Completion rule

Mobius accepts an iteration as complete only when all of these conditions are true:

1. The agent process exits successfully.
2. The agent prints the configured completion signal on its own line.
3. Every validation command exits with status code 0.

If validation fails, Mobius includes the output in the next agent prompt. A process failure or timeout stops the run. An unfinished run can be resumed later.

Commands

Command	Description
mobius init	Create project configuration.
mobius doctor	Check Python, agent commands, and validation settings.
mobius run <objective>	Start a run.
mobius resume [run-id]	Continue the latest run or a selected run.
mobius status [run-id]	Show one run and its latest validation result.
mobius runs	List recent runs.

Run mobius --help or mobius <command> --help for all options.

Configuration

Example mobius.config.json:

{
  "$schema": "https://raw.githubusercontent.com/satwiksps/mobius/main/mobius.config.schema.json",
  "agent": "codex",
  "maxIterations": 8,
  "timeoutMinutes": 30,
  "completionSignal": "<mobius>DONE</mobius>",
  "validation": [
    "python -m pytest",
    "python -m ruff check ."
  ],
  "agents": {}
}

Setting	Description
agent	Built-in or custom adapter name.
maxIterations	Total iteration limit, from 1 to 100.
timeoutMinutes	Timeout for each agent and validation process.
completionSignal	Exact line the agent prints when work is complete.
validation	Shell commands that must all pass.
agents	Custom command adapters.

Command-line options override the file for one run:

mobius run "Add request cancellation" \
  --agent claude \
  --max 5 \
  --check "python -m pytest" \
  --check "python -m ruff check ."

Preview the first prompt without launching an agent or writing run state:

mobius run "Upgrade the API client" --dry-run

Custom agents

Add an entry under agents. Use {prompt} in an argument to place the prompt there. If {prompt} is absent, Mobius sends the prompt through stdin.

{
  "agent": "aider",
  "agents": {
    "aider": {
      "command": "aider",
      "args": ["--message", "{prompt}"]
    },
    "internal": {
      "command": "company-agent",
      "args": ["run", "--stdin"]
    }
  }
}

Built-in adapters use stdin so objectives are not exposed in the operating-system process list.

State and security

Run state is stored as JSON under .mobius/runs/. Mobius does not send telemetry or upload this state.

Agent commands run with the current user's permissions. Validation entries are shell commands. Review mobius.config.json before running Mobius in an untrusted repository. Do not include secrets in objectives because prompts and selected output are stored in run history.

See SECURITY.md for the reporting process and security model.

Development

git clone https://github.com/satwiksps/mobius.git
cd mobius
python -m venv .venv

Activate the environment, then install and verify the project:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest --cov=mobius
python -m build
python -m twine check dist/*

Preview the website:

python scripts/serve_site.py

Open http://127.0.0.1:4173.

Deploy the website to Vercel

The root vercel.json publishes the static site/ directory. No build command or environment variable is required.

1. Push the repository to GitHub.
2. Open Vercel New Project.
3. Import satwiksps/mobius.
4. Keep the repository root as the Root Directory.
5. Select Other as the Framework Preset if prompted.
6. Deploy the project.

For deployment from a terminal:

npm install --global vercel
vercel
vercel --prod

The Vercel CLI creates .vercel/, which is ignored by this repository.

Release

The release workflow builds a source distribution and wheel, checks both artifacts, and publishes through PyPI Trusted Publishing. Configure the pypi environment and a trusted publisher for:

• PyPI project: mobius-agent
• GitHub owner: satwiksps
• Repository: mobius
• Workflow: release.yml
• Environment: pypi

Publishing a GitHub release then starts the workflow.

License

Mobius is licensed under the Apache License 2.0.