README
¶
A personal AI agent that lives entirely in your terminal. You talk to one agent; it orchestrates a crew of sub-agents to do the heavy lifting. A single binary, no daemon to babysit, no web UI, no external services to wire up.
[!WARNING] This project is in active development and built with love. Expect rough edges, and please report any bugs by opening an issue.
What it is
baifo is a terminal-first, single-user, local assistant. You launch it, land in a conversation with the root agent, and it decides on the fly when to spawn workers, load skills, search its memory, run shell commands, or call tools. There is no flow editor and no DAG to draw: the orchestration is the model's job, not yours.
It speaks the A2A (Agent-to-Agent) protocol, so other systems can drive your root agent the same way you do.
Features
-
Live sub-agent orchestration. The root spawns workers on demand, either from templates you define or composed at runtime (prompt, model, tools, skills and secret access chosen per spawn). Watch any worker run in real time, or jump into its chat and talk to it directly, without leaving the terminal.
-
Long-term memory that works offline. baifo remembers facts across sessions and retrieves them by meaning, not just keywords. It needs no vector database, no embedding API, and no network access: the memory works out of the box with the binary you downloaded.
-
Secrets the model never sees. Store credentials once; agents reference them by name. baifo injects the real value only at the moment a tool runs and scrubs it back out of the results before the model (or the logs, or the audit trail) ever sees it. Encrypted at rest, or plaintext for a throwaway box.
-
Sessions that survive. Close the terminal mid-task and pick the conversation back up tomorrow. Sessions persist locally, and you can list them and switch between them without losing context.
-
Tools, built in and pluggable. Ships with filesystem access (read, write, edit, search, run commands) and web fetch/search. Connect external MCP tool servers over HTTP or stdio, with OAuth handled for you.
-
Skills. Drop a Markdown playbook into your config to give agents domain knowledge (a coding style, a research protocol, a checklist) without bloating every prompt. Each agent opts into the ones it needs.
-
Tunable thinking. Dial each agent's reasoning effort from minimal to high. baifo maps it to whatever the underlying model supports and leaves it alone when the model has no such knob.
-
Pick your model per agent. Mix providers freely: a cheap fast model for routine workers, a heavyweight for the hard parts. baifo knows each provider's catalogue so it can size a worker sensibly.
-
Run it your way. Full interactive TUI, a headless REPL, one-shot commands from your shell, or a background server that exposes your agent over A2A.
Providers
baifo works with Anthropic, OpenAI and Gemini. Any OpenAI-compatible endpoint (a local Ollama server, OpenRouter, vLLM, ...) works too: declare it as an OpenAI provider pointed at its URL. Configure one or more and point each agent at whichever you want.
Got a Claude subscription? Declare an anthropic provider with auth: oauth,
log in with baifo provider auth <name> and use it directly, no API key needed.
More providers will get OAuth login as their terms allow it.
Install
Download the binary for your OS and architecture from the Releases page, then drop it on your PATH:
# Linux x86_64
curl -Lo baifo https://github.com/achetronic/baifo/releases/latest/download/baifo-linux-amd64
# macOS Apple Silicon
curl -Lo baifo https://github.com/achetronic/baifo/releases/latest/download/baifo-darwin-arm64
chmod +x baifo
sudo mv baifo /usr/local/bin/
Binaries: linux, darwin, windows, each for amd64 and arm64.
Getting started
baifo
On first run baifo walks you through creating its config directory. From there,
everything inside the TUI is driven by slash commands (/agent, /mcp, /skill,
/provider, /secret, /fact, /session, /worker, /settings), each with
autocomplete and inline help.
Commands
baifo launch the interactive TUI (default)
baifo --version print version
baifo --config-dir <path> point at a specific config directory
baifo chat [--message <text>] headless REPL, or a one-shot message with --message
baifo server run the A2A server in the background
baifo provider auth <name> log in to a provider with OAuth (anthropic type only for now)
baifo secrets set <name> store a secret (interactive, masked)
baifo secrets list list names and descriptions, never values
baifo secrets rotate <name> rotate a secret
baifo secrets unset <name> remove a secret
Configuration
baifo keeps everything in one directory: providers, agents, secrets, skills and
runtime knobs. The first run creates it for you; edit it by hand, through the
in-TUI slash commands, or with the built-in editor (syntax highlighting and
validation included). See docs/CONFIGURATION.md for the full guide.
Contributing
Contributions are welcome.
- Fork the project.
- Create a feature branch (
git checkout -b feature/AmazingFeature). - Commit your changes (
git commit -m 'Add AmazingFeature'). - Push the branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
Before pushing, run make build, make test and make lint.
License
Apache-2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
baifo
command
Command baifo is the entry point of the agent harness.
|
Command baifo is the entry point of the agent harness. |
|
internal
|
|
|
agent
Package agent builds ADK agents from baifo's high-level Spec.
|
Package agent builds ADK agents from baifo's high-level Spec. |
|
app
Package app is the top-level wiring of baifo: it owns the config, the providers, the MCPs registry, the storage layer, the builder, and the runner.
|
Package app is the top-level wiring of baifo: it owns the config, the providers, the MCPs registry, the storage layer, the builder, and the runner. |
|
audit
Package audit records tool calls into the SQLite audit table.
|
Package audit records tool calls into the SQLite audit table. |
|
config
Package config loads and resolves the on-disk configuration of baifo.
|
Package config loads and resolves the on-disk configuration of baifo. |
|
config/yamledit
Package yamledit provides comment-preserving edits to baifo.yaml.
|
Package yamledit provides comment-preserving edits to baifo.yaml. |
|
embeddings
Package embeddings provides an in-process text embedding engine backed by the nomic-embed-text-v1.5 model whose weights are compiled into the baifo binary.
|
Package embeddings provides an in-process text embedding engine backed by the nomic-embed-text-v1.5 model whose weights are compiled into the baifo binary. |
|
facade
Package facade declares the contract every client (TUI, HTTP server, CLI sub-commands) speaks to interact with baifo's core.
|
Package facade declares the contract every client (TUI, HTTP server, CLI sub-commands) speaks to interact with baifo's core. |
|
facts
Package facts implements baifo's long-term memory store.
|
Package facts implements baifo's long-term memory store. |
|
mcps
Package mcps wires MCP servers declared in baifo.yaml to ADK toolsets.
|
Package mcps wires MCP servers declared in baifo.yaml to ADK toolsets. |
|
mcps/builtin/browse
Package browse implements the in-process built-in browse MCP.
|
Package browse implements the in-process built-in browse MCP. |
|
mcps/builtin/browse/web
Package web is the low-level HTTP primitive used by the built-in browse MCP.
|
Package web is the low-level HTTP primitive used by the built-in browse MCP. |
|
mcps/builtin/filesystem
Package filesystem implements the in-process built-in filesystem MCP.
|
Package filesystem implements the in-process built-in filesystem MCP. |
|
modelcatalog
Package modelcatalog provides pure, offline utilities to match user-provided model endpoints and provider types to the built-in catwalk model catalogue.
|
Package modelcatalog provides pure, offline utilities to match user-provided model endpoints and provider types to the built-in catwalk model catalogue. |
|
providers
Package providers wires LLM providers declared in baifo.yaml into ready to use ADK models.
|
Package providers wires LLM providers declared in baifo.yaml into ready to use ADK models. |
|
providers/allproviders
Package allproviders blank-imports every built-in provider so that init() side effects register them with the providers registry.
|
Package allproviders blank-imports every built-in provider so that init() side effects register them with the providers registry. |
|
providers/anthropic
Package anthropic adapts the adk-utils-go Anthropic model into baifo's provider registry.
|
Package anthropic adapts the adk-utils-go Anthropic model into baifo's provider registry. |
|
providers/gemini
Package gemini adapts the upstream google.golang.org/adk Gemini model into baifo's provider registry.
|
Package gemini adapts the upstream google.golang.org/adk Gemini model into baifo's provider registry. |
|
providers/openai
Package openai adapts the adk-utils-go OpenAI model into baifo's provider registry.
|
Package openai adapts the adk-utils-go OpenAI model into baifo's provider registry. |
|
secrets
Package secrets implements the encrypted-at-rest secret store described in .agents/SECRETS.md.
|
Package secrets implements the encrypted-at-rest secret store described in .agents/SECRETS.md. |
|
server
Package server hosts the HTTP daemon that exposes baifo's agents over A2A and the rest of the system (workers, sessions, secrets, config) over a tiny REST surface.
|
Package server hosts the HTTP daemon that exposes baifo's agents over A2A and the rest of the system (workers, sessions, secrets, config) over a tiny REST surface. |
|
server/a2a
Package a2a exposes baifo's agents over the A2A (Agent-to-Agent) protocol so the TUI (and, later, remote clients) can converse with any agent without going through the in-process Facade.
|
Package a2a exposes baifo's agents over the A2A (Agent-to-Agent) protocol so the TUI (and, later, remote clients) can converse with any agent without going through the in-process Facade. |
|
sessions
Package sessions implements google.golang.org/adk/session.Service backed by a SQLite database.
|
Package sessions implements google.golang.org/adk/session.Service backed by a SQLite database. |
|
skills
Package skills loads skill packages from .baifo/skills/{slug}/SKILL.md.
|
Package skills loads skill packages from .baifo/skills/{slug}/SKILL.md. |
|
skills/installer
Package installer downloads and extracts skill packages distributed as .zip or .tar.gz archives.
|
Package installer downloads and extracts skill packages distributed as .zip or .tar.gz archives. |
|
storage
Package storage wraps modernc.org/sqlite with baifo-specific tables and schema versioning.
|
Package storage wraps modernc.org/sqlite with baifo-specific tables and schema versioning. |
|
tools/memory
Package memory wraps the long-term memory toolset shipped by adk-utils-go behind the same `Tools.ADKTools()` shape every other baifo-owned toolset uses (spawn, todos, meta).
|
Package memory wraps the long-term memory toolset shipped by adk-utils-go behind the same `Tools.ADKTools()` shape every other baifo-owned toolset uses (spawn, todos, meta). |
|
tools/models
Package models registers the list_models tool the root agent uses to discover which LLM models each configured provider offers.
|
Package models registers the list_models tool the root agent uses to discover which LLM models each configured provider offers. |
|
tools/skills
Package skills wraps ADK's skilltoolset behind the same `Tools.ADKTools()` shape every other baifo-owned toolset uses (spawn, todos, meta, memory).
|
Package skills wraps ADK's skilltoolset behind the same `Tools.ADKTools()` shape every other baifo-owned toolset uses (spawn, todos, meta, memory). |
|
tools/spawn
Package spawn registers the spawn / supervise tools the root agent uses to manage workers.
|
Package spawn registers the spawn / supervise tools the root agent uses to manage workers. |
|
tools/todos
Package todos exposes per-(agent, session) TODO management as ADK tools.
|
Package todos exposes per-(agent, session) TODO management as ADK tools. |
|
tui
Package tui implements baifo's terminal UI on top of charmbracelet's BubbleTea v2 stack.
|
Package tui implements baifo's terminal UI on top of charmbracelet's BubbleTea v2 stack. |
|
tui/components/editor
Package editor is baifo's embedded text editor component.
|
Package editor is baifo's embedded text editor component. |
|
tui/components/editor/mdhl
Package mdhl provides a per-line Markdown highlighter for the embedded editor.
|
Package mdhl provides a per-line Markdown highlighter for the embedded editor. |
|
tui/components/editor/yamlhl
Package yamlhl provides a single-line YAML syntax highlighter for the embedded editor.
|
Package yamlhl provides a single-line YAML syntax highlighter for the embedded editor. |
|
version
Package version is the single source of truth for the baifo binary's build metadata: semantic version, commit SHA and build timestamp.
|
Package version is the single source of truth for the baifo binary's build metadata: semantic version, commit SHA and build timestamp. |
|
watcher
Package watcher emits debounced events when files under the active .baifo/ directory change.
|
Package watcher emits debounced events when files under the active .baifo/ directory change. |
|
workers
Package workers owns the lifecycle of every sub-agent spawned by the root.
|
Package workers owns the lifecycle of every sub-agent spawned by the root. |