onefirewall-ai
A coding agent for your terminal and VS Code, powered by the OneFirewall AI Gateway or any OpenAI-compatible provider.
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 |
/agents [show <id> | stop <id|all> | new <name>] |
List agents and this session's runs, read a report, stop agents, create an agent file |
/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 agents [new <name> [--user]], 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
powershelltool, plusbashwhen Git Bash is installed; on macOS/Linuxbash. - Long tasks: a todo list for multi-step work, agents that work in parallel in the background (see Agents), 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 and agents (agents), ask_user, exit_plan_mode, plus MCP tools.
Agents
The agent can hand self-contained work to agents: separate workers with their own context and tools. Several run at the same time, in the background. The main agent tells you which agents are working and finishes its reply; you can keep chatting. When an agent finishes, its report comes back to the main agent as a new message: it checks what matters and tells you what was found, and gives the complete answer when the last one reports. (In -p runs, where nobody is there to see later replies, the turn waits for its agents instead.)
| Agent | |
|---|---|
explore |
Read-only research across the codebase; returns findings with path:line references |
plan |
Read-only; returns a concrete implementation plan (files, steps, risks, how to verify) |
general |
Multi-step tasks including edits, with the same tools as the main agent |
- Mention an agent to ask for it:
@explore how is caching invalidated? - Up to 4 agents run at once (
"max_agents"in settings.json, orONEFIREWALL_MAX_AGENTS). - Ctrl+C / Stop ends the main agent's turn; background agents keep going and report when they finish.
/agents stop allstops them. - Research agents (
explore,plan) are asked to wrap up after 20 tool calls and must report after 40. - Approvals an agent needs are labelled with the agent (
Agent #a2 general asks:). - Each agent's transcript is saved next to the session (
~/.onefirewall-ai/projects/<project>/<session>.agents/).
Custom agents are Markdown files in <project>/.onefirewall/agents/ (shared with your team) or ~/.onefirewall-ai/agents/ (all your projects). Create one with onefirewall-ai agents new security-reviewer or /agents new …:
---
name: security-reviewer
description: Reviews changes for security problems. Use after editing auth, input handling or crypto code.
tools: read_file, grep, glob, bash # optional: limit its tools (MCP: mcp__server)
model: Fast # optional: another model / workspace
permission_mode: plan # optional: can only be stricter than the session's mode
max_steps: 40 # optional
---
You are a security reviewer. Check the code you are pointed at for injection, auth bypass, secrets in code …
Report each finding with `path:line`, severity and a fix.
The main agent picks an agent by its description, so say when to use it. Project agents override user agents, which override the built-ins with the same name. onefirewall-ai agents lists them and shows files that failed to load.
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,
"max_agents": 4
}
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.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| onefirewall_ai-0.3.0.tar.gz | 167.7 kB | Without provenance | Details for onefirewall_ai-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| onefirewall_ai-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for onefirewall_ai-0.3.0-py3-none-any.whl |
Total release size: 317.3 kB
Release files / onefirewall_ai-0.3.0.tar.gz
| Download URL | onefirewall_ai-0.3.0.tar.gz |
|---|---|
| Size | 167.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
472bc70d63d14cc7afd0815718bae47a8c9a48465798c77f467bd54370337411
|
|
BLAKE2b-256 checksum How to use checksums |
92b8cdc96a4f51f32df4843ea7c208a2f2ec70628326a1892fe256372fdd5eb9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.7
|
Release files / onefirewall_ai-0.3.0-py3-none-any.whl
| Download URL | onefirewall_ai-0.3.0-py3-none-any.whl |
|---|---|
| Size | 149.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
17520d844da57980356417c8686d249736db8ef3e30a8a2a5b9ad4fed1949725
|
|
BLAKE2b-256 checksum How to use checksums |
1398f6d83182cfb5be2156edeb16e14d5f28c021f46add22fb21a9f9ccf16be4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.7
|
Security for onefirewall-ai 0.3.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.