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 |
/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
powershelltool, plusbashwhen Git Bash is installed; on macOS/Linuxbash. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.