Bog Agents

Pass through in harmony. Opinionated where it matters.

v0.10 — a production-ready AI agent framework built on LangGraph. Patient by design, watchful by default. It does the careful work so you don't have to wire it up yourself.

Three packages, one philosophy:

• bog-agents — the Python SDK. create_agent() returns a compiled LangGraph agent with file tools, a shell, git, sub-agents, plan mode, retry-with-backoff, and 90+ composable middlewares. Drop-in deepagents compatibility, too — create_deep_agent, DeepAgentState, filesystem permissions, harness/provider profiles.
• bog-agents-cli — a coding agent that lives in your terminal. 120+ slash commands, any LLM, persistent memory, MCP marketplace, /peat personal scheduler, /qa acceptance-criteria harness, /record + /replay, in-memory secrets vault, bog-agents drive for scripted runs, and a full headless surface so an AI agent or CI job can drive it without a human at the keyboard. Matte-swamp TUI.
• bog-agents-daemon — the patient watcher. Runs your agents on cron / file-change / webhook / git-push triggers; survives reboots; reports back via Slack / email / GitHub / file / webhook.

Built on LangGraph. MIT.

---

Philosophy

Out on the frontier a careful hand beats a fast one. Most agent frameworks hand you the parts and wish you luck. Bog Agents hands you a working agent — then lets you peel away or bolt on layers as you learn what the job actually asks for.

• Patient by default. Failures retry with bounded backoff. Hung commands time out. Provider hiccups don't kill the run. A crash drops a redacted panic dump so a bug report writes itself.
• Opinionated where it matters. Secure-by-default backends. A memory-only secrets vault that never touches disk. Structured event logging at every chokepoint. Tokens written atomically at 0o600 before the rename — no world-readable race window.
• No ceremony. pipx install bog-agents-cli && bog-agents and you have a working agent in under a minute. pip install bog-agents and one function call gets you a compiled agent.
• Composable. 90+ middlewares snap on or off. Subagents nest. Backends swap. The framework gets out of your way.

The bog is calm, deep, and unhurried. So is the agent.

---

Quick install

CLI (most folks start here)

# pipx is recommended — isolated install, clean PATH
pipx install bog-agents-cli

# or with uv (fastest)
uv tool install bog-agents-cli

# or plain pip
pip install bog-agents-cli

Provider extras:

pip install 'bog-agents-cli[anthropic]'        # Claude
pip install 'bog-agents-cli[openai]'           # GPT
pip install 'bog-agents-cli[bedrock]'          # AWS Bedrock
pip install 'bog-agents-cli[all-providers]'    # everything

Set one provider key and ride:

export ANTHROPIC_API_KEY=sk-ant-...     # or OPENAI_API_KEY, GOOGLE_API_KEY, AWS creds, ...
bog-agents --doctor-deep                # one-page health check
bog-agents                              # interactive TUI
bog-agents -p "explain this module" < src/agent.py   # one-shot

No key handy? Point it at a local Ollama model and nothing leaves the machine.

Keep current with /update inside the TUI — it checks PyPI, shows what will download, asks before installing, and upgrades the way you installed (uv tool / pipx / pip).

Daemon (ambient runner)

pip install bog-agents-daemon
bog-agents-daemon run --port 7878

See the daemon README for systemd / Windows-task / launchd installation, the REST API, trigger types, and output targets.

SDK only (for embedding agents in your own app)

pip install bog-agents

from bog_agents import create_agent

agent = create_agent(model="anthropic:claude-sonnet-4-6")
result = await agent.ainvoke({"messages": [{"role": "user", "content": "hi"}]})

See the SDK README for backends, middlewares, deepagents compatibility, and the full provider matrix.

---

What's new in 0.9.x

The 0.9 line is the run from a credible flagship toward 1.0. Each release hardened a different stretch of trail.

• 0.10 — Claude-Code-style auto mode, MCP server, self-verification, and two new SDK primitives. The marquee batch:
  • Permission modes (auto mode). Shift+Tab cycles default → accept-edits → plan; Ctrl+T toggles bypass; a live status indicator; a --permission-mode {default,acceptEdits,plan,bypass,paranoid} flag (plus --dangerously-skip-permissions).
  • bog-agents mcp-server. Expose the agent as an MCP server, so Claude Desktop, Cursor, Zed, or Copilot can delegate a whole coding task to it.
  • /self-review. Fan five reviewer lenses (correctness, security, maintainability, tests, over-claims) over your own diff → SHIP / FIX-FIRST verdict; --fix loops until clean.
  • /ci-fix. Read the branch's CI via gh, ingest the failing-job logs, and diagnose + fix.
  • @codebase semantic search, repo-committed .prompt.md files that auto-register as slash commands, agent-written auto-memories (a remember tool that persists conventions/gotchas to the AGENTS.md cascade), and shell pass-through (!command output now enters the agent's context so it can see what you ran).
  • SDK: bog_agents.evals (Dataset / scorers / run_evals / assert_pass_rate) and bog_agents.guardrails (composable input/output tripwire guardrails + create_agent(guardrails=[...])), plus a declarative .bog-agents/sandbox.toml. Hardened by a fresh Senior-Principal-Engineer audit (see REVIEW.md) and a competitive roadmap (ROADMAP.md).
• 0.9.4 — deepagents parity, headless driving, provider resilience. A first-class deepagents compatibility surface — create_deep_agent, DeepAgentState, FilesystemPermission, RubricMiddleware, and HarnessProfile / ProviderProfile keyed by provider:model — so a deepagents user can switch over without rewriting, and back again. A headless command surface (bog-agents command "/help") plus --jsonl structured streaming so agents and CI can drive the CLI non-interactively. Live-tested resilience across Anthropic, AWS Bedrock, and OpenAI.
• 0.9.1 — Bedrock, seamless. Automatic inference-profile resolution, /bedrock fix + /bedrock config, and auto SSO-credential refresh. Point at a model id; the SDK sorts out the rest.
• 0.9.0 — scriptable TUI, compliance, security sweep. bog-agents drive graduated to a full Pilot-backed runner; /compliance auditor with HMAC-sealed reports; a repo-wide security pass.

See CHANGELOG.md for the full history, including the 0.8.x flagship features (/peat, /qa, /record + /replay, the MCP marketplace) carried forward below.

---

The 0.8 flagship features (still here, still sharp)

/peat — your personal assistant

A long-lived in-process sub-agent with a hand-crafted persona. Schedules recurring jobs (cron, @every, @once), runs deep research with a five-phase plan, builds personalized digests from your /qa results and /replay recordings.

/peat schedule "0 9 * * 1-5 | summarize yesterday's QA results"
/peat research "vector databases" --focus pricing,perf
/peat digest --days 7

/qa — adaptive QA harness

Acceptance-criteria-driven QA plans. Ingest from Jira (via your MCP Jira tool), file, JSON, or stdin. Hybrid step model — agent / shell / http / mcp — with verdicts (exit_code, status, contains, regex, json_path). Outputs as Markdown, JSON, stdout, or Jira comment.

/record + /replay — sessions you can edit and re-run

/record captures user prompts, AI responses, and tool calls live. /record stop finalizes to a YAML file with auto-detected variables (Jira IDs, repo URLs, file paths) replaced by ${var} placeholders. /replay run prompts for any unfilled variables and dispatches to the agent.

Vault + Vars

Typed variable system shared by /replay and /qa: string, secret, enum, int, bool. Secrets live only in process memory; nothing persists to disk. Optional read-only OS-keychain bridge.

MCP marketplace

35+ curated servers across 9 categories: github, jira, gitlab, slack, postgres, mongodb, redis, bigquery, snowflake, supabase, aws, azure-devops, terraform, cloudflare, stripe, hubspot, notion, confluence, google-drive, discord, kubernetes, datadog, sentry, and more.

/mcp marketplace          # browse the catalog
/mcp install jira         # install from the catalog
/mcp add my-tool ...      # custom server

---

Repository layout

Path	What
libs/bog-agents/	The Python SDK. Compiled LangGraph agents, 90+ middlewares, pluggable backends, tool bundles, deepagents compatibility.
libs/cli/	The terminal CLI. Textual TUI, 120+ slash commands, MCP marketplace, headless command surface, bog-agents drive scripted runner.
libs/daemon/	The ambient daemon. Cron / file-watch / webhook / git-push triggers, REST API.
libs/acp/	Agent Client Protocol bridge for the Zed editor.
libs/harbor/	Evaluation / benchmark harness (Terminal Bench 2.0).
libs/partners/	Sandbox provider integrations (first-party source today: Daytona).
libs/vscode-extension/	VS Code integration.

Each package has its own pyproject.toml, Makefile, and version. SDK / CLI / daemon are released together on synchronized versions; the rest tag independently.

---

Working from source

git clone https://github.com/bogware/bog-agents
cd bog-agents

# Install + run the CLI from source
cd libs/cli
uv sync --reinstall
uv run bog-agents

Every package answers the same Makefile targets:

make test        # unit tests, no network
make lint        # ruff check + ruff format --diff + ty
make format      # ruff fix + ruff format

CI runs make lint + make test per package on every PR. See .github/workflows/ci.yml.

---

Documentation

Start with docs/ — the full documentation tree:

• Getting Started — install, first run, the five commands you'll use forever
• Cookbook — fifteen task-shaped recipes
• Troubleshooting — every common error, what it means, how to fix it
• Tips & Tricks — power-user moves
• Security Model — what's safe by default, what isn't, threat boundaries
• CLI deep dives: Drive runner · Slash command reference
• SDK guides: Quickstart · Middleware · Tool bundles
• Providers: AWS Bedrock
• Daemon: Quickstart
• Advanced: Expert Rules

Also:

• Per-package READMEs: SDK · CLI · Daemon
• Architecture — CLAUDE.md
• Changelog — CHANGELOG.md
• Issues — https://github.com/bogware/bog-agents/issues

---

License

MIT. See LICENSE.

---

Pass through in harmony.