Bitfield Ollama Agent user guide

What it is

Bitfield Ollama Agent is a terminal program. You give it a task in plain language — “summarize README.md”, “run the tests and fix the failure” — and it works through it with a local Ollama model, reading and editing files and running commands in the folder you point it at. In an interactive terminal it asks before writing files or running shell commands; you can also embed the same loop in your own Node software, or run it as a small local server that speaks the OpenAI chat API.

It has no account, no telemetry, and no cloud side. The only network traffic is to your Ollama server (and to any MCP servers or, if you route through Aura Wire AI Command Center, the providers you set up there). It is free for personal, non-commercial use under the Bitfield Creek Labs EULA.

Prerequisites

• Node.js 20+ — required for npm and the CLI
• Ollama running locally (default http://127.0.0.1:11434)
• A tool-capable model installed, e.g. ollama pull llama3.2 or ollama pull qwen3-coder:30b
• Optional: Aura Wire AI Command Center (Windows or macOS) — to see cost and traffic for agent runs, add guardrails, or route some tasks to cloud providers

Bitfield Ollama Agent uses only Node built-ins at runtime — no extra npm dependencies after install.

Installation

Recommended: install the published package globally so bf-agent is on your PATH.

npm install -g @bitfieldcreek/bf-agent
bf-agent models
bf-agent "what time is it right now?"

Try without installing

Use npx for a one-off run — useful for scripts or CI:

npx @bitfieldcreek/bf-agent "summarize README.md"

Offline or air-gapped

Download the versioned .zip from Bitfield Ollama Agent or direct download, extract it, and use the launchers in bin/ (bf-agent.ps1, bf-agent.cmd, bf-agent.sh).

Bitfield Ollama Agent is proprietary software — free for personal, non-commercial use. See the Bitfield Creek Labs EULA.

First run

1. Start Ollama and confirm a model is installed (ollama list).
2. Run bf-agent models to see how auto model selection classifies your installed models.
3. Ask a simple question: bf-agent "what time is it right now?"
4. In a project folder, try a file task: bf-agent "list the largest files here"

By default, interactive terminals use ask mode — file writes and shell commands prompt for y/N approval. Scripts and serve mode use unattended agent mode.

OpenAI-compatible server

Expose the agent loop behind the standard OpenAI API so any HTTP client — or an Aura Wire AI Command Center routing rule — can call it:

bf-agent serve --port 11435

• POST /v1/chat/completions — messages in, full agent loop (with tools) runs, chat.completion out. Streaming is supported via SSE replay.
• GET /v1/models — lists installed Ollama models.

Serve mode always runs unattended. Put Aura Wire AI Command Center guardrails in front if you need policy on tool execution or outbound traffic.

Pair with Aura Wire

Bitfield Ollama Agent is standalone — it does not require Aura Wire AI Command Center. But it also ships inside Wire: under Pipeline → Aura Router → Custom providers, Bitfield Ollama Agent is a built-in agent runtime alongside Copilot, Cursor, and Claude. Enable that row (choose the SDK sidecar, or the bf-agent CLI if it is on your PATH), then add a Router rule whose action is Delegate to agent → Bitfield Ollama Agent. Your IDE keeps its own backend; Wire hands matching turns to the agent loop.

Prefer to run the agent as a separate process? Use serve mode as an HTTP destination instead:

1. Run bf-agent serve on a port you choose (default example: 11435).
2. In Aura Wire AI Command Center, open Pipeline → Aura Router → Custom providers and add an OpenAI-compatible HTTP endpoint pointing at your serve URL.
3. Create a routing rule that sends agentic traffic to that provider — local Ollama stays free; cloud backends cost only what you route.
4. Chat from the Aura Wire AI Command Center extension, or point any OpenAI-compatible client at Wire's loopback /v1. Wire routes matching turns to Bitfield Ollama Agent; no editor extension is needed from Bitfield Ollama Agent itself.

One chat completion in = one full agent run out. Declare capabilities honestly on the provider row — Bitfield Ollama Agent executes tools itself, so client-side tool_calls stays unchecked (same convention as Wire's built-in agent runtimes).

See the Aura Wire user guide for install and pipeline setup.

SDK

Embed the same loop in your own software — install the package locally in a project or import after global install:

npm install @bitfieldcreek/bf-agent

import { createAgent } from "@bitfieldcreek/bf-agent";

const agent = await createAgent({
  model: "qwen3-coder:30b",
  workspaceRoot: "/path/to/project",
});

const { text } = await agent.run("run the tests and fix any failure");

Lower-level exports (AgentLoop, McpClient, createOpenAIServer, etc.) are available for custom wiring. See the package README on npm for the full API surface.

Common CLI options

• --model <name|auto> — Ollama model (default auto picks the best installed tool-capable model)
• --cwd <path> — workspace root for file and shell tools
• --mode ask|agent — confirm writes/shell in ask mode; unattended in agent mode
• --session <name> — persist and resume a conversation in the workspace
• --mcp "<command>" — attach an MCP server over stdio (repeatable)
• --max-steps <n> — cap model round-trips (default 10)

Privacy and data

• Nothing is sent to Bitfield Creek Labs. Bitfield Ollama Agent has no telemetry, no update check, no license call, and no account. Installing from npm contacts the npm registry like any package; the offline .zip does not.
• Your files go to the model you chose. File contents the agent reads and the task text are sent to Ollama at the base URL you configure. With local Ollama that stays on your machine. If you route through Aura Wire AI Command Center to a cloud provider, that provider receives them under its own terms.
• MCP servers you attach receive the tool arguments the model gives them, nothing else.
• Serve mode runs unattended — anything that can reach the port can run the agent in that folder. Keep it on loopback and put Aura Wire AI Command Center guardrails in front if you need approval policy.

What installs, and how to remove it

What Bitfield Ollama Agent puts on your machine

• The npm package — @bitfieldcreek/bf-agent in your global (or project) node_modules, with the bf-agent command on your PATH. With the .zip, only the folder you extracted.
• A .halo-agent/ folder inside each project you run it in — saved sessions when you use --session, edit checkpoints so you can undo a wrong turn, and a project search index if you build one. It is created only in folders where you run the agent, and it is safe to add to .gitignore.

It does not install services, change system or shell settings, modify other programs, or write outside the package folder and those per-project .halo-agent/ folders.

How to remove it completely

1. npm uninstall -g @bitfieldcreek/bf-agent (or npm uninstall in a project that installed it locally). For the .zip, delete the extracted folder.
2. Delete the .halo-agent/ folder from any project where you ran it.
3. If you added a custom provider or routing rule for it in Aura Wire AI Command Center, remove that row in Wire’s settings.

After these steps nothing from Bitfield Ollama Agent remains on the machine.

Troubleshooting

• Ollama connection errors — confirm Ollama is running and --base-url matches (default http://127.0.0.1:11434).
• Weak or missing models — run bf-agent models; pull a larger tool-capable model or pass --model explicitly.
• Context overflows — Ollama's default context is small; use --num-ctx (default 16384) or enable compaction via sessions on long tasks.
• Wire cannot reach serve — use a loopback URL Wire can access; check firewall rules if serve runs in Docker (try host.docker.internal from containers).