bog-agents-cli 0.9.0

Bog Agents CLI — your coding agent in the terminal, patient as still water. 80+ slash commands, any LLM provider (Anthropic, OpenAI, Bedrock, Google, Ollama and more), persistent memory, plan mode, /qa acceptance-criteria harness, /peat personal scheduler, /record + /replay, in-memory secrets vault, MCP marketplace with 35+ servers, deep doctor, panic dumps, and a matte swamp/neon-green TUI. One install, no code required. Pass through in harmony.

Bog Agents CLI

Pass through in harmony. Opinionated where it matters.

A coding agent that lives in your terminal. Point it at the work, step back, let it run.

No scaffolding. No config ceremony. One install and you've got file access, a shell, git, code review, planning, sub-agents — the whole outfit. Works with any LLM that does tool calls: Anthropic, OpenAI, Bedrock, Google, Ollama, and a dozen others.

Built on the Bog Agents SDK and LangGraph. MIT.

---

Why bog-agents-cli

You can have an agent in your terminal in under a minute. You can also build one out from there for years. The CLI is shaped to support both.

• Patient by default. Provider hiccups retry. Hung commands time out. Mouse-tracking escape sequences don't leak into your input box. Crashes drop a redacted panic dump for easy bug reports.
• Secure-by-default. Filesystem confined to the project root unless you explicitly opt out. Secrets live in an in-memory vault that's never persisted to disk. OAuth tokens written atomically with 0o600 mode set before the rename — no world-readable race window.
• Discoverable. Type / and a fuzzy menu shows you 120+ commands. The MCP marketplace browses 35+ servers across 9 categories. --doctor-deep probes every external dependency in under a second.
• Scriptable. bog-agents drive <script.yaml> runs the TUI non-interactively against a YAML grammar — slash commands, typed prompts, modal interactions, snapshots, assertions — so you can exercise every TUI surface in CI without a human at the keyboard.
• A bog aesthetic. Matte swamp palette — muted moss, lichen-grey, firefly-amber warnings, heather-rust errors. Ultima-inspired heavy-serif splash banner with rune anchors. A still pool, not a neon arcade.

---

Install

# pipx is recommended (isolates dependencies, gives you a clean PATH entry)
pipx install bog-agents-cli

# or plain pip
pip install bog-agents-cli

You'll need at least one provider API key in the env:

export ANTHROPIC_API_KEY=sk-ant-...   # Claude
export OPENAI_API_KEY=sk-...          # GPT
# or any of: GOOGLE_API_KEY, AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY,
# GROQ_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, FIREWORKS_API_KEY, ...

Or run local with Ollama — no key needed.

Verify the install:

bog-agents --doctor-deep

That probes Python, your config dirs, git, your provider keys, network reachability, your MCP config, and any recent crash dumps — one-page health summary in under a second.

---

30-second tour

bog-agents

Drops you into a TUI. Type a question, press Enter. The agent has filesystem, shell, git, and code-edit tools out of the box. Slash-tab auto-completes commands; /help opens the full reference.

Or one-shot it for scripts:

bog-agents -p "explain what this module does" < src/agent.py
bog-agents -n "fix the failing test in tests/test_auth.py" --auto-approve

-n is non-interactive (auto-exit), -p is pipe-friendly (clean stdout, no chrome).

---

What's new since 0.8.0

The most recent waves (post-flagship) have hardened the CLI toward a credible 1.0:

• Wave Y (0.8.8) — Audit-trail strict-hook warnings, first-run no-API-key actionable error, preview-server cap (5/instance) + stop_all_preview_servers tool, OAuth structured observability, opt-in MessageStore JSONL persistence for crash recovery, __all__ declarations on headline middleware modules.
• Wave X (0.8.7) — merge_worktree ref-injection fix, start_preview_server shlex parsing + DEVNULL, daemon dispatch errors captured on the run record.
• Wave W (0.8.6) — bog-agents drive scripted TUI runner (YAML grammar, Pilot harness, deterministic fake:/replay: model shims, SVG + text snapshots); tool-bundle pattern; canonical middleware-ordering test.

See CHANGELOG.md for the full history. The 0.8.0 notes below cover the original flagship release.

What's new in 0.8.0

A genuine flagship release. Five top-line capabilities and a hundred small refinements.

/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
/peat metrics                # in-process counters this session
/peat config show            # persona, goals, restrictions

Hybrid tool surface — full agent powers when you're chatting interactively, restricted (no shell, write-only into peat/) when running unattended.

/qa — adaptive QA harness

Acceptance-criteria-driven QA plans. Ingest from Jira (via your MCP Jira tool), file, JSON, or stdin. Plans are typed YAML; steps are agent / shell / http / mcp; verdicts use exit_code, status, contains, regex, or json_path. Outputs as Markdown, JSON, stdout, or Jira comment.

/qa new --from-jira PROJ-134
/qa run <plan_id> --var base_url=https://staging.example.com
/qa show <plan_id>

Plans live at <project>/.bog-agents/qa-plans/. Hand-edit the YAML to refine.

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

/record start 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 — secrets via masked input that route to the in-memory vault — then dispatches to the agent.

/record start  fix-login-bug
… use the agent normally …
/record stop                                                  # YAML written
# edit ~/.bog-agents/replays/<id>.yaml — refine var names, mark secrets
/replay run fix-login-bug --var jira_ticket=JIRA-456

Vault + Vars

A 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 via the keyring library.

MCP marketplace, expanded

/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 install jira
/mcp add my-tool /usr/local/bin/my-tool --flag value   # custom server
/mcp                                                    # live viewer

---

Day-to-day commands

/help	Full command reference
/model	Switch model on the fly
/profile	Apply a saved configuration preset
/plan	Toggle plan-mode (think-then-act)
/effort	Adjust thinking budget for the current model
/compact	Summarize and prune the current thread
/resume	Pick a recent thread to continue from
/threads	Browse all threads
/diff	Show changes since the agent started
/agent	Spawn / list sub-agents
/review	Structured code review on the current diff
/jury	Run the diff past N juror models, aggregate verdicts
/race	Run the same prompt past multiple models in parallel
/audit	Dependency vulnerability audit
/test	Test generation, coverage, audit
/build	Pipeline / recipe builder
/peat	Personal assistant + scheduler (see above)
/qa	Acceptance-criteria QA harness (see above)
/record / /replay	Capture and re-run sessions (see above)
/mcp	MCP server marketplace + manager
/quit	Exit

120+ commands total. Type / and start typing — fuzzy autocomplete will surface what you need.

---

Built-in observability

• Structured event logs at every chokepoint: agent run start/end, tool dispatch, scheduler fires, vault reads, provider calls. Stable event names, prefixed evt_* fields — drop straight into Splunk, Loki, or grep.
• /peat metrics — in-process counter snapshot for the current session.
• --doctor-deep — runtime probes of every external dependency.
• Panic dumps — uncaught exceptions land at ~/.bog-agents/crash/<ts>.log with redacted host info, versions, traceback, and recent metrics. Attach the file when you open an issue.

---

Configuration

Settings cascade — later layers override earlier:

1. Built-in defaults
2. ~/.bog-agents/settings.json — user global
3. <project>/.bog-agents/settings.json — project-local

Knobs include the auto-mode rule engine, Peat persona, MCP trust list, hooks, profiles, keybindings, and more. Every section is optional; you can ship without any settings file at all.

---

Working with sandboxes

Run the agent inside an isolated remote sandbox instead of on your host:

bog-agents --sandbox docker      # local Docker container
bog-agents --sandbox daytona     # remote daytona.io workspace
bog-agents --sandbox modal       # Modal sandbox (when the extra is installed)
bog-agents --sandbox runloop     # RunLoop sandbox (when installed)
bog-agents --sandbox langsmith   # LangSmith hosted sandbox

Today's first-party sandbox is Daytona (libs/partners/daytona/). The other providers are configurable via their respective extras; see the SDK docs for credentials and limits.

---

Headless modes

Flag	Use when
-n MSG	Run a task and exit. Great for CI / scripts.
-p MSG	Same as -n but quiet — clean stdout for pipes.
--json	Emit the result as a JSON envelope.
--prompt NAME	Run a saved prompt from your prompt library.
--prompt-vars JSON	Pass variable bindings to a saved prompt.
--pipeline NAME	Run a saved pipeline from .bog-agents/pipelines/.
--drive PATH	Run a YAML drive script that emulates a TUI user (Pilot-based, JSONL out).
--drive-stdin	Read the drive script from stdin instead of a file.
--serve	Long-running HTTP server mode.
--acp	Agent Client Protocol mode (Zed editor).

bog-agents drive example

# smoke.yaml
session:
  model: fake:Hello from drive.
  approval_mode: auto-all
steps:
  - "/help"
  - wait_for_idle: 5
  - expect_transcript_contains: "(?i)help|usage"
  - type: "summarize the README"
  - submit
  - wait_for_idle: 30
  - snapshot: artifacts/after-summary

bog-agents --drive smoke.yaml
# stdout (one JSONL row per step + summary):
# {"step":0,"action":"slash","ok":true,"duration_ms":42,...}
# {"step":1,"action":"waitforidle","ok":true,...}
# {"summary":{"total":6,"passed":6,"failed":0,"duration_ms":3210}}

Exit code = number of failed steps. The runner produces SVG + text snapshots for visual review and a JSONL transcript for diffing.

---

Always-fresh local development

git clone https://github.com/bogware/bog-agents
cd bog-agents/libs/cli
uv sync --reinstall
uv run bog-agents

uv sync --reinstall rebuilds every editable package from source. Add --no-cache to a single uv run to bypass the resolver cache for one shot.

---

Documentation

• This README + bog-agents --help
• Full docs: https://github.com/bogware/bog-agents/tree/main/docs — getting started, cookbook, troubleshooting, drive deep dive, tips & tricks
• Architecture overview: CLAUDE.md
• Repo: https://github.com/bogware/bog-agents
• Issues: https://github.com/bogware/bog-agents/issues
• Changelog: CHANGELOG.md

---

License

MIT. See LICENSE.

Pass through in harmony.