Skip to main content

onefirewall-ai

A coding agent for your terminal and VS Code, powered by the OneFirewall AI Gateway or any OpenAI-compatible provider.

PyPI Python License: MIT

The agent reads and searches your code, edits files, runs commands and tests, and keeps going until the task is done, asking for your approval before anything changes.

Install

pip install -U onefirewall-ai        # Python 3.10+
onefirewall-ai login                 # choose OneFirewall AI or any OpenAI-compatible provider

Then, inside a project:

onefirewall-ai                                   # interactive session
onefirewall-ai "fix the failing test in tests/test_api.py"   # one task

The VS Code extension (vscode/onefirewall-ai-vscode) uses this same engine.

Using it

Interactive session

❯ why does login fail when the email has uppercase letters?
❯ @src/auth.py add rate limiting to the login handler
  • Mention files with @path (Tab completes) to attach them.
  • Shift+Tab cycles the permission mode: ask before changes → auto-accept edits → auto → plan mode.
  • Ctrl+C interrupts the agent (it stops cleanly; the conversation stays usable). Ctrl+D exits.
  • Alt+Enter or a trailing \ inserts a newline.
Command What it does
/model [name] Show or switch the model / OneFirewall workspace
/mode default|accept-edits|auto|plan|bypass Change the permission mode
/plan Toggle plan mode: the agent researches and proposes a plan before changing anything
/undo Revert the file changes from the last turn
/compact Summarize the conversation to free context
/context, /cost Context window usage, token usage
/todos Show the agent's task list
/sessions, /resume [id] List and resume saved conversations
/init Create or improve AGENTS.md for the project
/mcp MCP server status
/new, /clear, /login, /help, /exit

One-shot and scripted use

onefirewall-ai "add type hints to utils.py"                    # live output, asks for approvals
cat error.log | onefirewall-ai "explain this error"             # piped input
onefirewall-ai -p "list the public API of src/" --output-format json      # non-interactive, for scripts/CI
onefirewall-ai -p "run the tests and fix failures" --permission-mode accept-edits
onefirewall-ai chat "what's the difference between TCP and UDP?"           # no tools

In -p (print) mode nobody can approve actions, so anything that needs approval is denied unless you pass --permission-mode accept-edits (edits allowed) or bypass (everything allowed — use only in a sandbox).

Options

Option
-c, --continue Continue the most recent session in this directory
--resume <id> Resume a saved session
--model <name> Use a specific model / workspace for this run
--permission-mode <mode> default, accept-edits, auto, plan, bypass
--cwd <dir> Work in another directory
--max-steps <n> Limit model steps per turn (default 100)
--output-format text|json|stream-json Output for -p

Other commands: onefirewall-ai sessions [view|delete] [id] [--all], onefirewall-ai mcp list|add|remove, onefirewall-ai login, onefirewall-ai version.

How the agent works

  • Grounded: it searches (grep, glob) and reads files before answering or editing; edits are rejected unless the file was read first and hasn't changed since.
  • Precise edits: exact-match replacement that preserves line endings (CRLF), BOM and encoding; tolerant of quote/whitespace/indentation slips; on a miss it shows the closest matching region so the model can correct itself.
  • Verifies: runs your tests/linters/builds and reads the exit code and the end of the output.
  • Right shell: on Windows it has a real powershell tool, plus bash when Git Bash is installed; on macOS/Linux bash.
  • Long tasks: a todo list for multi-step work, sub-agents for broad investigations, and automatic context compaction so long sessions don't overflow.
  • Recovers: retries transient gateway errors with backoff, adapts to provider quirks, and guards against loops and stalls.

Tools: read_file, edit_file, multi_edit, write_file, list_dir, glob, grep, bash / powershell, background_process, web_fetch, todo_write, task (sub-agents), ask_user, exit_plan_mode, plus MCP tools.

Permissions

Mode Behaviour
default Asks before edits, shell commands (read-only ones like git status run freely), web fetches and MCP tools
accept-edits File edits inside the project are applied without asking; commands still ask
auto Edits and commands run without asking, except risky ones — pushing to git, recursive deletes, discarding changes, publishing, cloud/infra changes, sudo, curl … | sh, global installs, writing outside the project — which pause with the reason
plan Read-only. The agent investigates and presents a plan; approve it to start
bypass Nothing asks. Only use in disposable environments

When asked, answer y (yes), a (always allow this kind of action for the session), n (no), or type instructions to send back instead.

Persistent rules go in ~/.onefirewall-ai/settings.json or <project>/.onefirewall/settings.json:

{
  "permissions": {
    "default_mode": "default",
    "allow": ["bash(npm test*)", "powershell(git diff*)", "edit(src/**)", "web_fetch(docs.python.org)"],
    "deny": ["bash(git push*)", "read_file(.env)"]
  },
  "max_output_tokens": 8192,
  "context_window": 128000,
  "max_steps": 100
}

Project instructions

Put an AGENTS.md (or ONEFIREWALL.md) at the root of your repository with build/test commands, architecture notes and conventions; the agent follows it. Files in subdirectories apply when the agent works there. Personal, uncommitted overrides go in ONEFIREWALL.local.md; instructions for all your projects go in ~/.onefirewall-ai/AGENTS.md. Run /init to generate a starting point.

MCP servers

onefirewall-ai mcp add github --env GITHUB_TOKEN=${GITHUB_TOKEN} -- npx -y @modelcontextprotocol/server-github
onefirewall-ai mcp add docs --url https://example.com/mcp --header "Authorization: Bearer $TOKEN"
onefirewall-ai mcp list

User servers live in ~/.onefirewall-ai/mcp.json. Servers defined by a repository (.mcp.json) run commands from that repository, so they only start after you trust the project when prompted.

Providers and configuration

onefirewall-ai login writes ~/.onefirewall-ai/access.json:

Provider Chat endpoint
onefirewall https://onefirewall.ai/api/v1/chat/completions
custom {endpoint}/v1/chat/completions (OpenAI, Groq, Together, Ollama, LM Studio, vLLM, …)

Environment variables override the file (useful in CI): ONEFIREWALL_PROVIDER, ONEFIREWALL_ENDPOINT, ONEFIREWALL_API_KEY, ONEFIREWALL_MODEL, ONEFIREWALL_CONTEXT_WINDOW.

~/.onefirewall-ai/SOUL.md (persona) and MEMORY.md (facts about you; synced from the OneFirewall dashboard) are added to the agent's instructions once you edit them.

Where data is stored

~/.onefirewall-ai/
├── access.json            provider, model, API key (keep this file private)
├── settings.json          permissions and limits (optional)
├── mcp.json               MCP servers (optional)
├── projects/<dir>/*.jsonl saved sessions (full transcripts, used by --resume)
├── file-history/          backups used by /undo
└── tool-output/           full output of long commands

Integrations

onefirewall-ai --stdio speaks a JSON-lines protocol (see docs/PROTOCOL.md) used by the VS Code extension; any editor or tool can drive the agent with it.

Development

pip install -e . pytest
pytest                      # unit + end-to-end tests against a fake model server
python evals/selftest.py    # validate the benchmark tasks
python evals/run.py         # run the benchmark against your configured model

License

MIT © OneFirewall

Metadata

Release files for onefirewall-ai 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onefirewall-ai 0.2.0
File Size Uploaded Provenance Actions
onefirewall_ai-0.2.0.tar.gz 130.7 kB Without provenance Details for onefirewall_ai-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onefirewall-ai 0.2.0
File Interpreter ABI Platform Actions
onefirewall_ai-0.2.0-py3-none-any.whl Python 3 none any Details for onefirewall_ai-0.2.0-py3-none-any.whl

Total release size: 254.9 kB

Release files / onefirewall_ai-0.2.0.tar.gz

Download URL onefirewall_ai-0.2.0.tar.gz
Size 130.7 kB
Tags Source
SHA-256 checksum
How to use checksums
32940faddc179508b35d39b28eddd65aca8c5490606bdb2d5914a912b4e67285
BLAKE2b-256 checksum
How to use checksums
cf6554779cc7a09a460ae69228a2947dad7fb556ade15c84442d5c55a6698e82
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Release files / onefirewall_ai-0.2.0-py3-none-any.whl

Download URL onefirewall_ai-0.2.0-py3-none-any.whl
Size 124.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
45d18dc29ffd102d0df6f726ed0e8b3a9635230e15df46871ae0fca5edda44ae
BLAKE2b-256 checksum
How to use checksums
9148638b5e4c131dbf893c4eab255cc23bdd695c1262ee2b6dbd8d1ee62d74f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Security for onefirewall-ai 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page