council

# Council [](https://www.npmjs.com/package/@moyu-build/council) [](https://www.npmjs.com/package/@moyu-build/council) [](LICENSE) [](https://modelcontextprotocol.io) [](https://nodejs.org) > Your personal thinking council for the AI era. > > Council turns your real conversations into reusable self-personas, then lets you convene them with mentors and roles across CLI, Web, and MCP. **Author**: Siyu Deng · **License**: MIT · **Status**: EvoTavern Hackathon 2026 **Stack**: Node 20+ · TypeScript · MCP Protocol · Anthropic Claude (Haiku 4.5) · Vite + React + Tailwind --- ## Hackathon Submission If you're new to this project, it's recommended to check out the presentation materials before diving into the code. | Audience | Material | Format | |---|---|---| | Judges / Mentors | [Presentation Deck](./相关材料/路演/横屏%2016-9%20比例/路演PPT.pdf) | PDF | | Judges / Mentors | [Presentation Source File](./相关材料/路演/横屏%2016-9%20比例/路演PPT.pptx) | PPTX | | Mobile Browsing | [Vertical Presentation Deck](./相关材料/路演/竖屏%209-16比例/council-pitch.pdf) | PDF | | Mobile Browsing | [Vertical Presentation Source File](./相关材料/路演/竖屏%209-16比例/council-pitch.pptx) | PPTX | | On-site Presentation | [6-minute Pitch Draft](./docs/pitch.md) | Markdown | | On-site Demo | [Demo Runbook](./docs/demo-runbook.md) | Markdown | | Narrative Background | [Story Narrative](./docs/story.md) | Markdown | For more presentation materials, architecture diagrams, and design drafts, see [docs/README.md](./docs/README.md). ## What is Council? Council is not an "agent that thinks for you," but a personal cognitive runtime that structures your thinking assets, making them reusable and callable. - `capture`: Precipitate real conversations into trackable cognitive materials - `distill`: Distill materials into your self-personas - `convene`: Convene self, mentors, and roles in a council to question and form conclusions - `export --mcp`: Expose this capability to clients like Claude Desktop, Cursor, and Cherry Studio In short: **Evolver enables agents to self-evolve. Council enables humans to self-evolve.** ## Get Started in 5 Minutes ```bash # 1. Installation (requires Node 20+) npm install -g @moyu-build/council # 2. Prepare API key echo "ANTHROPIC_API_KEY=sk-ant-..." > ~/.council.env # 3. Initialization council init # 4. Experience three main workflows council capture --file your-claude-chat.md # Capture a thinking conversation council distill --auto # Distill into self-persona council convene "Should I take this freelance job?" # Convene a council council refine self:reframe-before-execute # Let existing persona absorb new insights # 5. MCP integration with Claude Desktop / Cursor council export --mcp # Paste the printed configuration into claude_desktop_config.json / .cursor/mcp.json → Restart client ``` > As of v0.3, all commands (including `council live`) run purely on Node, no longer requiring Bun. --- ## Why Council? Each product for "personal AI" answers the same question: **How can AI/agents self-evolve and become more human-like?** Hermes lets AI grow with you. Second Me trains your digital twin. Evolver gives agents an evolution protocol. Huashu distills thinkers, allowing you to summon them into Claude. **Their subjects are AI/agents.** Council asks a different question: > **AI is accelerating self-evolution; what about humans? Who draws your curve?** It's not about letting AI think for you, but about letting **your thoughts**, like agents, **self-evolve** through structuring, adversarial councils, and cross-LLM summoning. **Evolver enables agents to self-evolve. Council enables humans to self-evolve.** This isn't a better agent; it's not an agent. It's a different **subject** – the subject is human. --- ## Core Workflow ``` Real conversations ──▶ capture ──▶ distill ──▶ Distill into your self-personas │ Your questions ──▶ convene ──▶ Convene self + mentor (Naval/Jobs/Munger) + role (devil's advocate) │ ▼ Independent statements ──▶ Mutual questioning ──▶ Comprehensive suggestions + clear disagreements │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ CLI Terminal Web Roundtable Live MCP Callable (Data Layer) (Council Visualization) (Claude/Cursor) ``` --- ## Two Usage Modes ### CLI (for developers/senior users' local runtime) ```bash council capture ./my-claude-chat.md # Capture conversation council distill --auto # Identify highlights + distill self-persona council convene "Should I launch an imperfect product?" ``` Each command's output is a Markdown file in the real file system. You can `git init`, modify by hand, or delete. ### Web (let others see your council) ```bash council convene "Should I go full-time with Council?" --watch ``` Same command, add `--watch`. Terminal logs continue printing, and a roundtable appears in the browser. Chairs light up to indicate speaking, dashed arrows indicate mutual questioning, and a parchment decision card appears in the center. ```bash # Or start live server only, without convening: council live # Open http://localhost:3737 in browser ``` ### MCP (let Claude Desktop / Cursor directly convene) ```bash council export --mcp # Paste the printed configuration into claude_desktop_config.json → Restart Claude Desktop ``` In Claude Desktop: > You: Help me decide whether to quit my job > Claude: *calls council_convene...* > Claude: [returns your council's structured conclusion] --- ## Directory Structure (user's council is the file system) ``` ~/.council/ ├── identity.md # Tell Council who you are (written by you) ├── config.yml # Model configuration (default Haiku 4.5) ├── personas/ │ ├── self/<name>.md # Distilled from your conversations │ ├── mentors/{naval,jobs,munger}.md # Pre-set │ └── roles/{devils-advocate,first-customer}.md ├── sessions/<date>-<slug>.md # Captured raw conversations ├── skills/<观点-slug>.md # Distilled highlights (named by viewpoint, e.g., authenticity guardrails.md) ├── transcripts/<date>-<slug>.md # Council transcript (human-readable) ├── live/<run-id>.jsonl # Council event stream (web/telemetry subscription) ├── exports/mcp-server/ # MCP export product └── .state/distilled.json # Anti-re-run index ``` Markdown + YAML + JSONL, no database. Users have full control. --- ## Installation ### Method A · NPM (recommended, 90% users) ```bash # Try it once, no global installation export ANTHROPIC_API_KEY=sk-ant-... npx @moyu-build/council@latest init npx @moyu-build/council@latest convene "Should I X" # Or global installation (install once, then directly use council) npm i -g @moyu-build/council council init council convene "Should I X" ``` **Requirements**: Node ≥ 20, Anthropic API key. > As of v0.3, `council live` (web roundtable live) also runs on Node (`node:http` + `ws`), no longer requiring Bun runtime. All npm users can use it out of the box. --- ### Want to run from source / contribute code? See [`CONTRIBUTING.md`](CONTRIBUTING.md). Source-level development recommends Bun (hot reloading + TS running directly), but Node can also run. --- ## Command List | Command | Purpose | |---|---| | `council init` | Initialize ~/.council/ | | `council capture [--file/--clipboard]` | Capture a conversation as a session | | `council distill [id\|--auto]` | Distill session into highlights + self-personas | | `council persona list` | List all personas | | `council persona add <path\|url>` | Import external SKILL.md as mentor | | `council convene "<question>" [--watch]` | Convene a council. `--watch` opens web roundtable live | | `council live` | Start live server only (port 3737), without convening | | `council feedback <transcript-id>` | Three-level rating h/g/o | | `council evolve` | Scan entire library, mark stale, and suggest merges | | `council merge <a> <b>` | Merge two personas | | `council export --mcp` | Export MCP Server configuration | | `council serve` | Start MCP Server (stdio) | --- ## MCP Tools | Tool | Purpose | |---|---| | `council_who_am_i` | Pull user identity file + available personas (once per session) | | `council_list_personas` | List available personas (lightweight) | | `council_convene` | Convene a council, return transcript | | `council_ask_persona` | Ask a persona directly | | `council_should_capture` | Judge if a conversation is worth capturing before capture | | `council_capture_this` | Capture current conversation and distill immediately | | `council_bootstrap_identity` | Backtrack identity draft based on existing self-personas | ### LLM Invocation Mode (v0.4+ automatically chooses) Council **automatically judges** which LLM invocation mode to use in MCP mode: | Mode | When enabled | Features | |------|---------|------| | **BYOK** (Anthropic API) | Configured `ANTHROPIC_API_KEY` | ⚡ Streaming / No popup / Use your API billing | | **MCP Sampling** (borrow from host) | No key configured, client supports sampling | 🆓 Use client subscription / Non-streaming / Client may popup approve | > **In human words**: If you've already paid for a subscription on Claude Desktop / Claude Code, **no need to configure another API Key**—Council will automatically request the host to run LLM. It also works on some supported clients. **CLI and `council live` (local browser) still require BYOK**, as they have no "host" to borrow. > > **Trade-offs**: Sampling is non-streaming (council loses real-time feel), and some clients may pop up approve each time. Heavy users are recommended to configure a key for BYOK mode for a better experience. ### Access MCP Clients **Claude Code (zero configuration, borrow client LLM)**: ```bash claude mcp add council -- npx -y @moyu-build/council@latest serve ``` > If you don't pass `-e ANTHROPIC_API_KEY`, Council will automatically use Sampling mode to borrow Claude Code's LLM. To use BYOK (streaming + no popup), add `-e ANTHROPIC_API_KEY=sk-ant-...`. **Claude Desktop / Cursor / Cherry Studio (modify JSON configuration)**: Zero configuration (borrow host LLM, recommended): ```json { "mcpServers": { "council": { "command": "npx", "args": ["-y", "@moyu-build/council@latest", "serve"] } } } ``` BYOK (better experience, streaming + no popup): ```json { "mcpServers": { "council": { "command": "npx", "args": ["-y", "@moyu-build/council@latest", "serve"], "env": { "ANTHROPIC_API_KEY": "sk-ant-..." } } } } ``` > The client will trigger `npx` to pull the latest version on the first startup, and then hit npm cache for a fast restart. The `@latest` tag ensures you're aligned with the main branch. > Data falls into `~/.council/`, shared across clients with the same identity file. > Startup logs are in stderr (Claude Desktop in `~/Library/Logs/Claude/mcp.log`), with the first line indicating whether `anthropic-api` or `mcp-sampling` is used. ## Architecture (Three-layer Decoupling) ``` ┌─ CLI ─────────────── MCP Server ───────────── Web (Browser/Pake app) ─┐ │ │ │ POST /api/command │ │ writes ▼ broadcast │ │ ┌──────── Event Bus (events.ts) ────────┐ │ │ │ │ │ │ ├─▶ ~/.council/live/*.jsonl (Ground Truth) │ │ │ ├─▶ stderr (CLI Rendering) │ │ │ └─▶ WebSocket (Web Subscription) │ │ │ │ │ convene / capture / distill / evolve <── Business Engine │ │ │ │ │ ▼ │ │ Claude Haiku 4.5 │ └──────────────────────────────────────────────────────────────────────┘ ``` Three-layer strict decoupling: - **Data Layer** (`~/.council/`): File system is the single source of truth. Git-trackable, owned by users. - **Runtime** (CLI + MCP + Live Server): Business logic, event bus, API calls. Clean stdout (MCP protocol security), events go out through file + subscription channels. - **Presentation Layer** (CLI rendering / web roundtable / MCP client): Read-only subscription to events. Don't know each other's existence. --- ## Design Philosophy 1. **Your Data Belongs to You** — `~/.council/` is pure Markdown. Git-trackable, auditable, exportable, deletable. No database, no cloud dependency. 2. **Protocol Above Product** — Compatible with SKILL.md / MCP / AGENTS.md standards. Character skills can be used as mentor personas, Second Me models as self-persona slots, and distilled skills as ability modules. **Council doesn't compete, it's a collaborative layer**. 3. **Disagreement is a Feature** — Your council is always the one you don't need. Synthesis must mark "still in disagreement", no compromise allowed. 4. **Subtraction is Discipline** — CLI + Markdown + MCP + one-page web. No web UI dashboard, no accounts, no training, still valid in 10 years. 5. **The Subject is Human** — Not a feature difference, but a worldview difference. Any competitor copying Council's features, as long as they aim for AI/Agent self-evolution, they can't replicate Council. --- ## Status · Next Steps - ✅ **L0**: Event bus + structured synthesis + persona visual metadata - ✅ **L1**: Web HTTP/WS server + Vite/React roundtable page + `--watch` - ✅ **L2**: Web capture/distill process (paste → distill → convene) - ✅ **L3**: Feedback loop C (refine + evolve) + cross-LLM verification (Cursor / Claude Desktop) - ✅ **L4**: Live server migration from Bun to Node native http + ws — zero extra installation for npm users - Future: Clipboard listening for auto-capture, desktop global shortcuts, Council-to-Council collaboration Full architecture see [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) · Presentation materials see [`docs/`](./docs/) · Contributions see [`CONTRIBUTING.md`](./CONTRIBUTING.md). --- ## License MIT © Siyu Deng