Skip to main content
Glama

Bokken

ci PyPI License

An agentic harness for Design Thinking — one executable, instrumented loop. Test with wood; commit steel when it counts.

Bokken encodes the Empathize → Define → Ideate → Prototype → Test loop as an executable, event-sourced, governed process. Point it at something tangible — an app repository, business and performance metrics, interview transcripts — and it runs the loop either with you in it (Founder mode, interactive at the terminal) or fully autonomously against a governed synthetic persona panel (the Dojo). Every step lands in the Journal, an append-only, hash-chained process ledger, and a finished run produces two deliverables:

  1. The Session Dossier — outcomes, the process narrative with receipts, and the full machine-readable evidence graph.

  2. The handoff — build-ready OpenSpec specifications for the validated concept's MVP, ready for a coding agent to ingest and implement.

Terminal-first and MCP-consumable. Python. No GUI.

The run report: verdict-first, journal-derived, honest A finished run: verdict-first report, simulated-run banner, receipts on every number (live example).

Why

Meeting AI documents the past; canvas tools hold sticky notes; app generators build artifacts without the understanding. Bokken is a harness, not a bot: it owns the process state, the method library, the evidence, and the audit trail — so every output can answer how do you know, who said so, what did we reject, and why. In an era of "AI did it", the defensible asset is a replayable account of the reasoning. That account is the Journal, and it is built in, not bolted on.

Related MCP server: coolplatform-cs-agent

How it works

brief + inputs ──► intake ► empathize ► define ► ideate ► prototype ► test ► complete
(repo, metrics,      │         ▲          ▲                             │        │
 interviews)         │         └──────────┴───────── loop-backs ────────┘        │
                     ▼                                                           ▼
              the Journal (append-only, hash-chained JSONL; state = replay)      │
                     │                                                           │
                     ├──► Session Dossier (outcomes · narrative · evidence graph)
                     ├──► OpenSpec handoff (MVP specs for a coding agent)
                     ├──► Reports (PPTX deck + portable HTML with OST view)
                     └──► bokken validate ► real-human interviews (terminal/Twilio)
                                            rescore the register with reported evidence
  • Stages are a real state machine with entry/exit criteria and first-class loop-backs; every transition is journaled with the evidence that justified it.

  • Facilitation is auditable: every intervention is a named, budgeted move from the Kata (reframes, assumption flags, timebox pivots, devil's advocate, loop-back proposals…), logged like a tool call — executed or suppressed, with reasons.

  • The Dojo is governed simulation: personas are cast with documented sampling and role agents (skeptic, feasibility, viability), answer only from the ingested corpus with citations or abstain (abstentions become research debt), never see the sponsor's preferred answer, and never evaluate work they helped create (contamination firewall). Runs stop on budgets, novelty floors, or criteria — never on "the answer looked good".

  • Honesty is enforced in code: synthetic contributions are labeled at the record level; decisions resting on simulated or assumed evidence carry requires real validation; the Dossier states what the run did not do; and the handoff turns contradicted assumptions into exclusions and validation debt into mandatory tasks. None of this is configurable away.

  • The code is read before anyone is asked: when the corpus includes code, Empathize opens with a citation-validated map of current capabilities (journaled as current_capability interpretations) that targets the UI feature tests; every corpus source carries its evidence role — code establishes implemented behavior, never desired intent.

  • The product is tested, not assumed: with --app-url the run walks the real UI (SPA-aware), functionally exercises every inventoried feature with works/broken/unclear verdicts, and wireframe_html prototypes are generated on the repo's own CSS tokens and exercised in a browser before the test panel judges them.

  • The market is on the record: after the concept is chosen, an explicitly authorized web research pass (--allow-web-research) produces competitors with overlap, sourced signals, regulatory notes, and risks — journaled as reported evidence that feeds the assumption register.

  • Real humans close the loop: bokken validate turns the research debt into an interview guide and an agentic interviewer moderates real participants (terminal, or Twilio SMS/WhatsApp behind the [interview] extra) — consent is asked first, once, and journaled before any question goes out; every exchange is reported human evidence, and the register is rescored against it.

  • The run travels: bokken pack produces one portable archive with an honest manifest (verdict, cost, sha256 index); --deliverables-only for external sharing states exactly what was omitted.

  • The output executes: bokken handoff --emit claude-code|cursor|codex renders the OpenSpec package as an execution prompt your coding agent follows directly — evidence pointers included.

  • The deliverables are yours: bokken export --theme acme.json white-labels the report (brand color, label, footer) without touching a single journal-derived claim.

  • Learnings compound: every finalized run feeds the insights library; the next run on the same product starts knowing what was supported, contradicted, or broken — with session provenance on every borrowed line.

  • Fusion cost architecture: frontier lanes judge (Fable 5 / Opus 5), a cached Sonnet 5 sidekick lane reads; bokken costs reports spend, cache hit-rate, and grounding health (abstentions forced by unresolved citations) from the journal.

  • Crash-safe by construction: sessions are durable, named, and resumable; kill the process anywhere and bokken run continues from the ledger.

Quickstart

See a complete run first — no API key, no network, no cost (sample output):

uvx bokken demo
# halt: completed - dossier generated; handoff specs generated; report exported
# (pptx + html)
# you were charged $0.00 - 0 network calls, 0 real tokens; the journaled
# usage is an illustrative live-run profile: ~$8 list price across 48 calls

With the [ui] extra installed, the demo also walks a bundled mock of the product in a real browser: per-feature functional tests, screenshots, and an honest broken finding land in the journal and both reports (the receipt then reads ~$10 across 63 calls — the profile the published gallery shows).

Then point it at something real. Requires uv and a provider API key — Anthropic is the default, OpenAI via the extra:

uvx bokken doctor        # one-screen environment check, every gap with its fix
uvx bokken init --from-repo . --yes   # or draft the brief FROM your repo
                         # (templates still available: saas-retention,
                         #  consumer-app, internal-tool)

# default provider
export ANTHROPIC_API_KEY=...

# OpenAI provider
uvx --from 'bokken[openai]' bokken version
export OPENAI_API_KEY=...
uvx --from 'bokken[openai]' bokken new retention --provider openai --model gpt-5 \
  --reasoning-effort high --brief bokken-brief.json --mode dojo

Every bokken run states the typical cost and the session's token guardrail before spending, and prints a receipt ($ · model calls) whenever it halts; bokken costs <name> breaks it down per stage × prompt × class.

Claude Desktop: install natively with the one-click bundle — bokken-<version>.mcpb (double-click; prompts for key/workspace/roots; the demo needs no key).

Optional extras: uvx --from 'bokken[ui]' bokken ... unlocks the UI walkthrough and per-feature tests (plus uvx playwright install chromium once); bokken[interview] unlocks the Twilio interview channel.

Development mode (the repo is the runtime — what the maintainers use):

git clone https://github.com/maglionejm/bokken && cd bokken
make install
export ANTHROPIC_API_KEY=...

Run the loop autonomously against your product, your numbers, and your research:

uv run bokken new retention \
  --mode dojo \
  --brief brief.json \
  --repo ./myapp \
  --metrics data/kpis.csv \
  --discussion research/interview-ana.md

uv run bokken run retention          # halts at each stage gate
uv run bokken gate retention approve
uv run bokken run retention          # ... approve gates until:
# halt: completed (stage: complete)
# finalization: dossier generated; handoff specs generated; report exported (pptx + html)

uv run bokken journal retention --type decision   # every decision, with dissent
open .bokken/sessions/retention/dossier/dossier.md
ls   .bokken/sessions/retention/handoff/openspec/changes/

Or be the counterpart yourself: --mode founder and Bokken interviews you, you pick the winning option, and you score the assumption register.

The deliverables

Session Dossier (dossier/): Part A — outcomes with ledger receipts on every claim; Part B — the process narrative (pivotal moments, why the losers lost, dissent and how it was handled, loop-backs with triggers); Part C — dossier.json, the full evidence graph (insights↔evidence, idea lineage, IBIS decision records, persona provenance cards, model traces).

Reports (report/): a strategic PPTX deck (decision tables, HILL banner, verdict-colored register) and a portable single-file HTML (chaptered, agent deliberation, per-feature UI test cards, Opportunity Solution Tree, next actions) — deterministic renderings of the Journal.

OpenSpec handoff (handoff/): a strict OpenSpec change package (proposal.md, design.md, capability specs with SHALL requirements and WHEN/THEN scenarios, tasks.md) plus traceability.json mapping every requirement to the ledger events it rests on. Copy it into any repo's openspec/changes/, run openspec validate --strict, and hand it to your coding harness. See docs/handoff.md.

Surfaces

CLI

demo · init · new · run · step · stop · status · list · gate · back · journal · dossier · handoff · export · pack · costs · opportunities · backlog · diff · estimate · validate · library · doctor · version · serve — every read verb speaks --json; exit codes are stable (0 success, 1 unexpected, 2 refused)

MCP

bokken serve (stdio): 14 tools + 4 resources over the same core with identical result shapes; agent actions are journaled with the client's handshake identity — see docs/mcp.md

Documentation

Doc

What it covers

docs/architecture.md

The layer stack, runtime loop, design invariants, blueprint mapping

docs/operating.md

Setup, creating and driving runs, gates, budgets, auditing, deliverables, troubleshooting

docs/events.md

The Journal: envelope, hash chain, and the full event taxonomy v1

docs/handoff.md

The OpenSpec handoff contract and ingestion workflow

docs/mcp.md

MCP tools, resources, and client setup

docs/agents.md

The agent registry: every actor, its lane, its model, and what it may never do

docs/codebase-map.md

Navigation map for agents: each subpackage's seams, invariants, and top gotcha

docs/gotchas.md

Hard-won failure modes: symptom, rule, and the PR that paid for it

docs/recipes.md

Task cookbooks: files to touch in order, and the test that rides along

Project structure

bokken/
├── src/bokken/
│   ├── journal/       # the ledger: schema, store, replay, queries (the moat)
│   ├── orchestrator/  # the DT state machine, runner, gates, budgets
│   ├── stages/        # the five stage engines (both modes) + code exploration
│   ├── kata/          # the facilitation move library
│   ├── panel/         # persona casting, typed corpus, grounding, firewall
│   ├── models/        # model routing, journaled invocations, prompts
│   ├── interview/     # consent-gated real-human validation interviews
│   ├── dossier/       # Session Dossier generation
│   ├── handoff/       # OpenSpec MVP-spec generation + executable adapters
│   ├── report/        # PPTX deck + self-contained HTML report, themes
│   ├── demo/          # the scripted, zero-network demo provider
│   ├── cli/           # the terminal surface
│   ├── mcp/           # the MCP surface
│   ├── contract.py    # one result contract for both surfaces
│   ├── library.py     # cross-run learnings (workspace-level)
│   ├── bundle.py      # bokken pack: one portable archive + manifest
│   ├── diffing.py     # bokken diff: cross-run comparison
│   ├── backlog.py     # bokken backlog: ranked validation to-do
│   └── estimate.py    # bokken estimate: modeled pre-flight cost
├── openspec/          # bokken's own spec-driven development (13 capabilities)
├── docs/              # documentation + the GitHub Pages site
├── tests/             # the whole loop runs offline against a fake provider (no API key)
└── scripts/           # live smoke run + MCPB bundle build

Development

make check    # ruff + pytest + openspec validate --strict  — the definition of done

Bokken is built spec-first with OpenSpec — the same format it hands off. Every behavior change starts as a change under openspec/changes/ and is archived into openspec/specs/ when implemented. See CONTRIBUTING.md and CLAUDE.md (the project constitution).

Once a concept is selected, an authorized deep web research pass (--allow-web-research) produces a structured market record — competitors with overlap, sourced signals, regulatory notes, risks — that feeds the assumption register and the reports.

The full actor roster — lanes, models, and what each agent may never do — lives in docs/agents.md.

Models: claude-fable-5 (effort high, Opus fallback) for research and challenge agents, claude-opus-5 (adaptive, effort high) for execution and documentation, claude-sonnet-5 for the delegated sidekick lane (verbatim corpus reads, mechanical UI stepping), claude-haiku-4-5 for lightweight signal extraction — every call journaled with prompt version, token usage, and request id. The entire test suite runs offline.

Naming

A bokken is the wooden practice sword: you rehearse with wood until failure is boring, and commit steel only when the risk is understood. Inside the harness: the Journal (the faithful record of how understanding was earned), the Kata (named, drilled, repeatable moves), the Dojo (where practice runs full-contact with no client in the room), and sparring sessions (runs against synthetic participants).

Stability and support

As of v1.0, these surfaces are stable: the Journal event taxonomy (v1, with schema_version on every event and bokken_version in each session's config snapshot), the CLI verbs and their --json shapes, the MCP tools and resources, and the deliverable formats (Dossier, handoff package, reports). Experimental and subject to change: tuning knobs (ideation.*, empathize.*, ui_tests.*, walkthrough.*), the Twilio interview channel, and the insights-library record shape.

Active development is currently paused while we gather real-user feedback: issues are triaged, pull requests are welcome, and the spec-first workflow (openspec/) is the front door for contributions — see CONTRIBUTING.md.

License

Apache-2.0. Copyright 2026 Juan Martín Maglione and Marc Puig.

Created and maintained by Juan Martín Maglione and Marc Puig.

Available Tools

14 tools
cost_reportC

Cost report from the journaled model calls (list-price estimate, cache hit rate).

Inputs: name (required).

create_session_toolB

Create a Design Thinking session. The brief needs problem_space, target_segments, success_criteria, risk_tolerance, and may declare inputs (repo path, metrics/discussion/document files). Input paths are resolved on the server and confined to the authorized input root(s): traversal, escaping symlinks, and outside absolute paths are refused.

Inputs: name (required), brief (required), mode, seed, +6 more.

export_reportB

Export the run report (PPTX deck + self-contained HTML) and return the paths.

Inputs: name (required).

generate_dossierC

Generate the Session Dossier and return the export paths.

Inputs: name (required).

generate_handoffA

Generate OpenSpec MVP specifications for the validated concept, ready to be ingested by a coding harness (refused for killed concepts).

Inputs: name (required).

get_statusC

Where the session is and what blocks progress.

Inputs: name (required).

list_sessions_toolA

List sessions in the workspace.

Inputs: no named parameters.

query_journalB

Read ledger events with the same filters and canonical form as the CLI.

Inputs: name (required), type, actor, limit, +2 more. Returns: result

request_loopbackC

Loop back to an earlier stage (test->define, test->empathize, define->empathize).

Inputs: name (required), reason (required), to_stage (required).

resolve_gateB

Approve or reject the pending gate (rejection requires a reason).

Inputs: name (required), resolution (required), reason.

run_sessionB

Advance the session to its next halt (gate, input, stop, or completion). Completed runs are finalized automatically: Dossier, then handoff specs.

Inputs: name (required).

step_sessionB

Advance the session by at most one stage.

Inputs: name (required).

stop_sessionA

Stop the run (journaled human-initiated stop); the session stays resumable.

Inputs: name (required), reason.

submit_inputC

Answer the session's pending Founder-mode question, then run_session again.

The answer is attributed to this client's handshake identity, so the engine that consumes it journals agent-supplied (simulated) evidence rather than human testimony.

Inputs: name (required), answer (required), question_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target distinct actions and resources, but run_session and step_session both advance a session and could be confusable depending on intent. get_status and query_journal also overlap somewhat as read-only status/history surfaces, though their descriptions clarify the difference.

    Naming Consistency4/5

    The set mostly follows a verb_noun pattern (run_session, stop_session, resolve_gate, generate_handoff), but cost_report is a noun-style command and list_sessions_tool/create_session_tool carry a _tool suffix not present elsewhere. These are minor deviations rather than a systemic naming problem.

    Tool Count5/5

    14 tools is well-scoped for a Design Thinking session management server. Each tool maps to a meaningful lifecycle action or output, and there is no obvious redundancy or bloat.

    Completeness4/5

    The surface covers session creation, status, advancement, stopping, gates, loopbacks, journaling, reporting, and final handoff generation. Minor gaps exist, such as no explicit session update/delete or single-session detail tool, but the core workflows have no dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agent clients to safely connect to tools and execution resources through MCP with authorization, approvals, audit, chat-context isolation, SSH/Docker access, and long-running command session tracking.
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides MCP tools that let an agent retrieve customer account, product usage, interaction, and support summaries, and create follow-up tasks after user approval.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP agents to help a person understand their goals, discuss obstacles, plan actions, and record progress in their own words, with a scoped API client and human-led workflow.
      1
      AGPL 3.0