convez.ai
MCP ServerDevOps & InfraestruturaAvançado
salacoste

Oh My BMAD — Plataforma Autônoma de Desenvolvimento Auto-hospedada

salacoste/oh-my-bmad

Claude Code worker governado por Telegram + console via event sourcing typed

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma Telegram e console em superfícies de controle para um worker Claude Code. Implementa event sourcing com log append-only, materialização single-writer em SQLite e capability tiers para aprovar ações privilegiadas. Infraestrutura observável e recuperável de falhas.

Instalação

$npx convez-ai salacoste/oh-my-bmad

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
11
Contribuidores
1

Casos de uso

  • Orquestrar tarefas de desenvolvimento autônomo com aprovação manual
  • Manter log auditável e recuperável de todas as ações do agent
  • Controlar execução de código Claude através de Telegram ou CLI

Veredito

Plataforma sólida para quem precisa de agent loop observável e auditável. Stack maduro (FastAPI, SQLite, aiogram), design event-sourced é robusto, mas setup e conceitos exigem experiência em Python/DevOps.

README

A tradução para o português deste README ainda está na fila.


What this is

A platform that turns Telegram and a local console into the control surfaces for a Claude Code worker. Commands you send become typed events on an append-only log. A single-writer materializer turns the log into queryable SQLite state. Capability tiers gate every privileged action; operator approval events gate the high-risk ones. Crash the process and it rebuilds itself from the log on next start.

It's deliberately boring infrastructure — Python 3.12, FastAPI, aiogram, SQLite WAL, Docker Compose, stdio MCP. The novelty is in how the boring pieces compose, not in any one piece.

Current repo state: Phase 17 shipped — destructive lifecycle apply readiness is documented without implementing destructive apply. Latest tagged release is v1.3.0; this checkout contains later Phase 10–17 work. See docs/index.md for the master entry point.

How it works (at a glance)

flowchart LR
    subgraph operator [Operator surfaces]
        TG[Telegram bot]
        CLI[console CLI]
    end

    subgraph api [HTTP API]
        RA[registry-api<br/>FastAPI · /v1/tasks]
    end

    subgraph spine [Event spine]
        LOG[(append-only JSONL log<br/>byte-stable canonical JSON)]
        STATE[registry-state<br/>SINGLE WRITER<br/>materializer + idempotency cache]
        DB[(SQLite WAL<br/>tasks · sessions · events<br/>idempotency · snapshots)]
    end

    subgraph mcp [MCP servers · stdio · capability-tier gated]
        TR[task-registry]
        SR[session-registry]
        CB[clawhip-bridge<br/>sole emission surface]
    end

    subgraph worker [Worker plane]
        WW[worker-wrapper<br/>Claude Code CLI subprocess]
    end

    TG --> RA
    CLI --> RA
    RA --> LOG
    LOG --> STATE --> DB
    LOG -.read-only tail.-> TG
    LOG -.read-only tail.-> CLI
    WW --> CB
    WW --> TR
    WW --> SR
    TR & SR & CB --> LOG
    DB --> RA

Three properties hold the whole thing together: only one writer, only-ever-append, and the bytes on disk are byte-stable. The rest of the rules in _bmad-output/project-context.md exist to protect them.

Engineering highlights

  • Event-sourced spine, byte-stable canonical JSON. Two identical envelopes serialize to byte-identical output. Replay-determinism is a property of the encoder, not a hopeful claim. (deep-dive →)
  • Single-writer invariant (FR26), statically enforced. services.<A> cannot import services.<B>. EventLogWriter is the only opener-for-write on the log. A CI gate (scripts/checks/check_imports.py) rejects PRs that drift this boundary.
  • Idempotency by UUIDv7. Every command threads the triggering UUIDv7 through a per-key asyncio.Lock → cachetools TTLCache → SQLite write-through with a 7-day retention contract. 100 concurrent retries for the same key invoke the factory exactly once. (deep-dive →)
  • Crash-injection tested. A real Docker stack gets shot at deterministic emission points; recovery is asserted to produce byte-for-byte equivalent state. Partial writes are detected and rejected by a poison-pill mechanism in the writer. (deep-dive →)
  • Capability tiers with mandatory deny-path tests. Four tiers (read / bounded-write / repo-mutation / high-risk-with-approval). Three tests mandatory per MCP tool boundary: deny-path, default-deny, escalation. @pytest.mark.security is non-skippable. (deep-dive →)
  • Multi-runtime workers. Claude Code, Codex, and Gemini adapters behind a RuntimeAdapter protocol with per-task selection, fallback, and handoff. Worker pool auto-scaling (FC-P6-1).
  • MCP tooling fleet — 8 stdio servers. git, github, verification, memory/wiki, artifact, browser, task-registry, session-registry — all behind tier-gated build_server, per-server env isolation, and scoped credentials.
  • HMAC approval signing with offline verification. Operator decisions are HMAC-signed at emission; just verify-approval works offline. Key rotation with fingerprint tracking and /key-status surface.
  • Supply chain hardening. SLSA L2 provenance, cosign keyless signing, CycloneDX SBOM, license-compatibility publish gate, just verify-images — all wired into the release pipeline.
  • Metrics subscriber with cardinality discipline. Tail-loop subscriber exposes /metrics (FastAPI); 51 canonical timeseries baseline, cardinality-bounded regression test at 10K tasks, p95 <1ms.
  • mypy --strict everywhere, ruff for lint and format. No half-on rule families. Per-file ignores live in ruff.toml, not sprinkled. Bandit-S rules gate the obvious vulnerability classes (eval, pickle, yaml.load, subprocess shell=True, weak hashes).
  • AI-agent rule digest as injected context. _bmad-output/project-context.md — 386 rules across 7 categories, hand-built with multi-agent review to capture the load-bearing constraints that aren't obvious from the code alone.
  • Upstream forks behind adapter shims. upstream/omc + upstream/clawhip vendored at pinned SHAs; direct imports of vendored internals are rejected by static analysis. Contract tests gate semantic drift.
  • Three-layer secret hygiene. Pre-commit scanner + structlog sanitizer wired before the renderer + secret.accessed audit events. F-string interpolation of tokens / request bodies / PII is a banned anti-pattern in code review. Per-server env scoping ensures each MCP child sees only its own vars.

Tech stack

LayerChoice
RuntimePython 3.12 · Node.js (only inside the Claude Code worker subprocess)
Build / workspaceuv ≥ 0.5 (workspace, 24 members) · just ≥ 1.14 (operator recipes)
HTTP APIFastAPI (only on registry-api)
Telegramaiogram v3 (webhook + outer-middleware allowlist, ADR-0001)
Consoletyper CLI with full command parity
StorageSQLite + WAL · aiosqlite · Alembic (additive-only within a major)
Event logappend-only JSONL, canonical JSON, fdatasync
MCPstdio by default, Streamable HTTP where configured · 9 servers (task-registry, session-registry, clawhip-bridge, git, github, verification, memory, artifact, browser)
WorkerMulti-runtime: Claude Code, Codex, Gemini — supervised, auto-scaled
Observability/metrics endpoint · trace_id propagation · structlog (JSON) + sanitizer
Testspytest · pytest-asyncio (strict) · hypothesis · crash-injection · mutation gate (cosmic-ray, 82%+) · 3200+ tests
Toolingruff (E F I UP B SIM N + S) · mypy --strict · pre-commit · pytest-randomly
DeployDocker Engine ≥ 24 · Docker Compose v2.24+ · SLSA L2 + cosign keyless signing
DRLitestream WAL replication to S3/B2/R2/MinIO (opt-in)

Exact versions live in uv.lock. Secrets are operator-provisioned via .env with per-server env isolation and scoped credentials.

Quickstart

# Prereqs: Docker Engine ≥ 24, Docker Compose v2.24+, uv ≥ 0.5, just ≥ 1.14
#   brew install uv just                              # macOS
#   curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux (uv)

git clone https://github.com/salacoste/oh-my-bmad && cd oh-my-bmad
uv sync --frozen --all-packages    # NOT --no-dev — strips test deps
uv run pre-commit install
just bootstrap-verify              # workspace imports must be green
cp .env.example .env
$EDITOR .env                       # secrets + tunnel choice
just dev                           # macOS overlay; Linux base compose
docker compose ps                  # core services should be Up/healthy within 60s

Full deployment guides: VPS (Linux) · macOS host · Deployment entry point

How this project gets built — the BMad workflow

This codebase was produced by — and continues to follow — the BMad structured development workflow: a 4-phase lifecycle (analysis → planning → solutioning → implementation) where each phase has explicit inputs, outputs, and gates. Every artifact in _bmad-output/ is a real document produced by a real skill in that workflow.

Phase 1 — Analysis           → product-brief / PRFAQ + research
Phase 2 — Planning           → PRD + UX design
Phase 3 — Solutioning        → architecture + epics & stories + test framework + CI
Phase 4 — Implementation     → sprint plan → (create-story → validate → atdd →
                                              dev-story → code-review → trace → nfr) ×N
                              → retrospective at every epic boundary

Phase 1 took 10 epics / 88 stories, with retrospective + deferred-work governance at every epic boundary. The current repo has progressed through 17 phases — event spine, multi-runtime workers, a 9-server MCP fleet, browser automation, supply-chain hardening, remote MCP transport, mTLS, historical replay, event-log lifecycle management, lifecycle-operation safety, docs/backlog reconciliation, archive-aware task history, and destructive lifecycle apply readiness planning — with zero open GATED deferred items. The full per-phase walkthrough, skill catalog, and "how a new feature enters the workflow" decision tree is documented separately:

➡️ docs/bmad-workflow.md — the complete workflow this project follows.

If you're an AI agent picking up new work on this codebase, that file is the process companion to _bmad-output/project-context.md (the rules digest) — read both before writing code.

Documentation map

This repo documents itself in three layers, by audience.

For AI agents (read first if you're an agent)

For humans

Deep-dives on load-bearing concepts

Planning artifacts (for the why)

What's interesting about this codebase

A few things worth a look even if you don't intend to run it:

  • The AI-agent rule digest (_bmad-output/project-context.md). A 7-category, 386-rule reference designed to be injected into the context window of a coding agent. Built collaboratively with multi-perspective review; explicitly distinguishes enforced rules (CI gates) from discipline rules.
  • The deep-dive explanations (docs/explanations/). Each one walks a load-bearing concept (event spine, idempotency, recovery, capability tiers) end-to-end with Mermaid diagrams and source-grounded code samples.
  • The single-writer enforcement (scripts/checks/check_imports.py). Service separability isn't a doc rule; it's a CI gate that statically rejects PRs that drift the boundary.
  • The crash-injection test tree (tests/crash-injection/). Real Docker stack, deterministic kill points, byte-for-byte state equivalence as the assertion.

Built with

uv FastAPI aiogram v3 Pydantic v2 SQLAlchemy SQLite structlog Hypothesis ruff mypy Claude Code

License

MIT. Use freely; attribution welcome; no warranty.

Status

Current development state — Phase 17 shipped. Latest tagged release: v1.3.0. Shipped phases in this checkout:

PhaseScopeEpics
1Core platform — event spine, registry, Telegram, console, workers1–7.5
2Observability — supply chain, trace_id, metrics, HMAC approvals, budget enforcement, Litestream DR8–13
3MCP tooling fleet — git, github, verification, memory/wiki, artifact14–19
4Browser automation — Playwright MCP, screenshot, tab management20–22
5Multi-runtime — Codex, Gemini adapters, per-task selection, handoff26–29
6Server execution pool — Postgres, state machine, multi-worker30–34
7Reliability hardening — heartbeat detection, structured output, env isolation35–40
8Platform hardening & debt closure — zero open deferred items41–45
9Operational excellence — PR drafts, runbooks, stale TODO cleanup46–48
10Remote MCP transport — Streamable HTTP + bearer auth50–55
11mTLS — internal Docker-network TLS profile and CA tooling56–59
12Historical event replay — replay engine, validation, snapshots, task history60–63
13Event log lifecycle — archive manifest, hot+archive replay, package streaming64–68
14Event log lifecycle operations — ADR-0025, non-destructive dry-run, hot-only task-history boundary69–73
15Lifecycle documentation reconciliation and backlog triage74–75
16Archive-aware task history — read-only hot+archive history query76–80
17Destructive lifecycle apply readiness — planning/safety contract only, no destructive implementation81–85

Phase 17 is shipped as a planning/readiness-only safety-contract phase. Destructive lifecycle apply is still unimplemented, and object-storage lifecycle jobs plus scheduled retention remain future work. Zero open GATED deferred items.

Issues and discussion welcome — security reports per SECURITY.md.

Ver o original no GitHub

Bom para

Relacionados