bokken
This server lets you create and drive Design Thinking sessions (founder/dojo modes), advance or stop runs, manage gates and loopbacks, answer founder-mode questions, inspect the journaled ledger, and produce deliverables (handoff specs, dossier, reports, cost breakdowns).
Create and configure sessions:
create_session_toolaccepts a name, brief (problem space, segments, criteria, risk tolerance, inputs), mode, provider, model, panel size, budgets, reasoning effort, seed, and gate policy.Run or step sessions:
run_sessionadvances to next halt (gate/input/stop/completion, auto-finalizes),step_sessionadvances one stage at a time.Control execution:
stop_sessionhalts a run (resumable, journaled);resolve_gateapproves/rejects pending gates with reasons.Request loop-backs:
request_loopbackmoves to an earlier stage (test→define, test→empathize, define→empathize).Provide founder-mode input:
submit_inputanswers pending questions; answers are attributed as simulated evidence.Inspect state and history:
get_statusshows where the session is and blockers;list_sessions_toollists workspace sessions;query_journalreads ledger events with filters (type, actor, stage, limit, since_seq).Generate deliverables:
generate_handoffcreates OpenSpec MVP specs (refused for killed concepts),generate_dossierbuilds the Session Dossier,export_reportproduces PPTX + HTML reports.Monitor costs:
cost_reportreturns list-price estimates and cache hit rates from journaled model calls.
Enables conducting real user interviews via Twilio SMS/WhatsApp channels, supporting the bokken validate workflow to gather human evidence and rescore assumption registers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bokken Run a dojo session for onboarding and show me the dossier"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bokken
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:
The Session Dossier — outcomes, the process narrative with receipts, and the full machine-readable evidence graph.
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.
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 evidenceStages 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_capabilityinterpretations) 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-urlthe run walks the real UI (SPA-aware), functionally exercises every inventoried feature with works/broken/unclear verdicts, andwireframe_htmlprototypes 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 asreportedevidence that feeds the assumption register.Real humans close the loop:
bokken validateturns 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 isreportedhuman evidence, and the register is rescored against it.The run travels:
bokken packproduces one portable archive with an honest manifest (verdict, cost, sha256 index);--deliverables-onlyfor external sharing states exactly what was omitted.The output executes:
bokken handoff --emit claude-code|cursor|codexrenders the OpenSpec package as an execution prompt your coding agent follows directly — evidence pointers included.The deliverables are yours:
bokken export --theme acme.jsonwhite-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 costsreports 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 runcontinues 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 callsWith 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 dojoEvery 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 |
|
MCP |
|
Documentation
Doc | What it covers |
The layer stack, runtime loop, design invariants, blueprint mapping | |
Setup, creating and driving runs, gates, budgets, auditing, deliverables, troubleshooting | |
The Journal: envelope, hash chain, and the full event taxonomy v1 | |
The OpenSpec handoff contract and ingestion workflow | |
MCP tools, resources, and client setup | |
The agent registry: every actor, its lane, its model, and what it may never do | |
Navigation map for agents: each subpackage's seams, invariants, and top gotcha | |
Hard-won failure modes: symptom, rule, and the PR that paid for it | |
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 buildDevelopment
make check # ruff + pytest + openspec validate --strict — the definition of doneBokken 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 toolscost_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Toolbox dynamically routes to all MCPs in the Smithery registry based on your agent's need. When a…
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Work with roles, tasks and delegated agent work within current workspace permissions. Setup: In a remote MCP client that supports Streamable HTTP and OAuth, add https://platform.samuelz.com/api/v1/mcp/operator?toolset=agent. Sign in to Samuelz and select your authorized workspace. An active workspace membership and the relevant module permissions are required. Review the requested permissions before authorizing. Existing approval requirements continue to apply.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- FlicenseNot gradedqualityNot gradedmaintenanceProvides MCP tools that let an agent retrieve customer account, product usage, interaction, and support summaries, and create follow-up tasks after user approval.-
- AlicenseNot gradedqualityBmaintenanceEnables 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.1AGPL 3.0
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP clients to query and debug trace data, sessions, exceptions, route decisions, metrics, prompts, datasets, and annotation queues. Supports configurable tool groups and read-only safety modes.-