bondulance

A local-first, offline, multi-agent coding assistant TUI written in Rust.

bondulance drives a local LLM through a running llama.cpp server over HTTP, gives the model tools to read and write code, search the repository, run commands, and do git work — all inside an isolated sandbox. Each agent run happens in a per-session git worktree, so your main checkout stays untouched until you review and accept the changes.

Key Features

• Fully offline — inference runs through a local llama.cpp server; no cloud APIs
• Sandboxed execution — shell, git, and MCP commands run in a bwrap sandbox with filesystem isolation
• Worktree isolation — every session works in a dedicated git worktree; you accept or discard changes at the end
• Multi-agent — a planner decomposes complex tasks and delegates to specialized sub-agents that run in parallel
• Rich toolset — file read/write/edit, regex search, shell commands, git operations, web fetch/search, image viewing, background services, and MCP tool import
• Persistent sessions — conversation history and background services persist per project, so you can resume where you left off
• Context-aware — hybrid repository context with language markers, semantic search (embeddings), and automatic context compaction
• Extensible — agent capabilities are defined in data files (YAML frontmatter) and hot-reload without restarting

How It Works

┌─────────────────────────────────────────────────────────────┐
│                      bondulance TUI                          │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────────┐ │
│  │ Repo Tree │  │ Chat Pane    │  │ Metrics / Sub-agents  │ │
│  └──────────┘  └──────────────┘  └───────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
                           │ prompts & events
┌──────────────────────────▼──────────────────────────────────┐
│                    Agent Loop                                │
│  Planner → Sub-agents (parallel, bounded by slots)          │
└──────────────────────────┬──────────────────────────────────┘
                           │ tool calls (validated)
┌──────────────────────────▼──────────────────────────────────┐
│              bwrap Sandbox + Git Worktree                    │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌─────────────────────┐  │
│  │ Shell  │ │  Git   │ │  MCP   │ │ Background Services │  │
│  └────────┘ └────────┘ └────────┘ └─────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP (OpenAI-compatible API)
┌──────────────────────────▼──────────────────────────────────┐
│              llama.cpp Server (local)                        │
└─────────────────────────────────────────────────────────────┘

1. You type a prompt in the TUI
2. The agent loop sends it to the local LLM along with context and available tools
3. The model responds with text and/or tool calls
4. Each tool call is validated against its schema and executed inside the sandbox
5. Results are fed back to the model until the task is complete
6. Changes live in an isolated git worktree — you review them in a diff view and accept or discard
7. Accepted changes are merged back into your main checkout

Prerequisites

• Rust (edition 2024) — to build from source
• bubblewrap (bwrap) — sandbox for command execution
• git — version control and worktree isolation
• llama.cpp — local inference server (llama-server)
• socat — required for SSH socket bridging in the sandbox

Installing Dependencies by Distribution

Distribution	Command
Arch Linux	sudo pacman -S bubblewrap socat git llama.cpp
Fedora	sudo dnf install bubblewrap socat git (build llama.cpp from source)
openSUSE	sudo zypper install bubblewrap socat git (build llama.cpp from source)
Ubuntu/Debian	sudo apt install bubblewrap socat git (build llama.cpp from source)
macOS	brew install bubblewrap socat git llama.cpp

Note: llama.cpp may not be available in all package managers. You can build it from source if needed.

Installation

From Source

git clone https://github.com/<your-org>/bondulance.git
cd bondulance
cargo build --release

The binary will be at target/release/bondulance.

Install Globally from a Local Clone

cargo install --path .

This installs both bondulance and socket-sshd (the custom SSH server used inside the sandbox) into your ~/.cargo/bin directory.

Quick Start

1. Start a llama.cpp Server

bondulance requires a running llama.cpp server with tool-use support. Start it with:

llama-server \
  -m /path/to/your/model.gguf \
  --jinja \
  --metrics \
  --host 127.0.0.1 \
  --port 8080

Key flags:

• --jinja — enables Jinja2 chat templates (required for tool use)
• --metrics — exposes /metrics endpoint for the TUI metrics pane

2. Initialize Your Project

From your project root (must be a git repository):

# Create a commented default config at .bondulance/config.toml
bondulance init

# Create default agents, skills, and AGENTS.md template
bondulance setup

This creates:

• .bondulance/config.toml — project configuration (endpoint, model, agent limits, tools, etc.)
• .bondulance/compaction.md — context compaction prompt
• .agents/skills/ — six default skills (implementation, code-review, git-commit, documentation, architect, how)
• .agents/default.agent.md — the default agent definition
• AGENTS.md — project-specific agent instructions (customize this!)

3. Check Your Setup

bondulance doctor

This verifies bwrap, git, the git repository, socket-sshd, socat, the llama.cpp server, and the configured model. Fix any reported issues before proceeding.

4. Run bondulance

bondulance

The TUI launches with three panes: a repository tree, a central chat pane, and a metrics pane. Type your prompt and press Ctrl+S to send it.

5. Review and Merge

When the agent finishes, press Ctrl+M to review the changes in a diff view. You can:

• Accept (Ctrl+Enter) — merges the changes into your main checkout
• Discard — throws away the changes

Configuration

The main config file is .bondulance/config.toml. Key sections:

[server]
endpoint = "http://127.0.0.1:8080"   # llama.cpp server URL
model = ""                            # model name (empty = server default)

[model]
temperature = 0.7                     # sampling temperature

[agent]
max_steps = 50                        # max tool-loop steps per agent
max_sub_agents = 4                    # max sub-agents per run
max_parallel = 2                      # max parallel sub-agents

[tools]
allowed = []                          # empty = all tools allowed
summarization_threshold = 200         # lines before read_file summarizes
search_result_cap = 50                # max search_files matches
shell_output_cap = 10000              # max shell output bytes
shell_timeout = 60                    # shell command timeout (seconds)

[network]
proxy_url = ""                        # egress proxy (empty = none)
allowed_domains = []                  # empty = all domains allowed

[tui]
syntax_theme = ""                     # syntect theme for file viewer

Environment overrides:

• BONDULANCE_ENDPOINT — overrides server.endpoint
• BONDULANCE_MODEL — overrides server.model

Run bondulance init --force to regenerate the fully commented config file.

CLI Commands

Command	Description
bondulance	Run the TUI (default)
bondulance run	Run the TUI (explicit)
bondulance init	Create default config (.bondulance/config.toml)
bondulance init --force	Overwrite existing config
bondulance setup	Create default agents and skills
bondulance setup --force	Overwrite existing skills
bondulance doctor	Check system dependencies
bondulance themes	List available syntax highlighting themes
bondulance --debug	Enable HTTP request/response logging to .bondulance/debug.log
bondulance -h, --help	Show help
bondulance -V, --version	Show version

Keyboard Shortcuts

Global

Key	Action
Ctrl+C	Cancel current run / Quit
Ctrl+Q	Quit application
Ctrl+M	Merge back worktree changes (review diff)
Ctrl+L	Select model
Ctrl+A	Select agent
Ctrl+N	Reset chat (same agent)
Ctrl+K	Compact context
Ctrl+T	Toggle tree pane
F1	Toggle help overlay

Input (focused)

Key	Action
Ctrl+S / Ctrl+Enter	Send prompt
Enter	Insert newline
Tab	Switch focus to next pane

Chat (focused)

Key	Action
Enter / Space	Toggle tool call fold
↑ / ↓	Navigate collapsible entries
Ctrl+F	Start search
Ctrl+N / Ctrl+P	Next / Previous search match
Esc	Exit search / Close viewer

Merge Review

Key	Action
Ctrl+Enter	Accept changes
Esc	Discard changes (with confirmation)
Tab	Cycle focus: File tree → Diff → Buttons
← / →	Switch between Accept/Discard buttons
Enter	Select file / Activate focused button

Menus (Session / Model / Agent)

Key	Action
↑ / ↓ or j / k	Navigate
Enter	Select
Esc	Close menu

Help

Press F1 at any time to see the full help overlay with all shortcuts.

Safety & Isolation

bondulance is designed to keep your code and system safe:

• Sandbox: All shell, git, and MCP commands run inside a bwrap sandbox. Only the session worktree is writable; system directories are read-only.
• Worktree isolation: The agent never touches your main checkout. Changes are merged only when you explicitly accept them.
• Network control: Egress goes through a per-domain allowlist proxy with localhost bypass. You control which domains the agent can reach.
• Schema validation: Every tool call is validated against its JSON Schema before execution.
• Step limits: Agent runs are bounded by configurable step budgets and sub-agent limits.
• No self-authorization: Agent definitions load outside the sandbox, so an agent cannot grant itself additional permissions.

Customizing Agents

Agent capabilities are defined in data files, not code:

• AGENTS.md — project-specific instructions (loaded by all agents)
• .agents/skills/ — reusable skill definitions (YAML frontmatter + Markdown)
• .agents/default.agent.md — the default agent definition

Changes to these files hot-reload automatically — no restart needed.

Each skill file has YAML frontmatter:

---
name: code-review
description: Run tests and linter, review code.
caller_scope: all
tools: [shell, read_file, search_files]
---

Troubleshooting

• bondulance doctor — run this first when something isn't working; it checks all dependencies and gives distribution-specific fix suggestions
• --debug flag — logs all HTTP requests/responses to the llama.cpp server in .bondulance/debug.log
• Server not responding — make sure llama-server is running with --jinja and --metrics, and that the endpoint in config matches
• Sandbox issues — ensure bwrap and socat are installed and that your user has permission to use bwrap (some systems require unprivileged user namespaces)

License

See the project's license file for details.