Twining

Twining MCP Server enables coordinated agent work across Claude Code and other MCP clients by providing a shared blackboard, decision tracking with rationale, selective context assembly, a lightweight knowledge graph, local semantic search, and an embedded web dashboard. All state is stored in human-inspectable JSON files, easily git-trackable, and accessible to your local workflow for transparent collaboration and traceability.

How to use

You integrate the Twining MCP Server with your MCP client setup to enable shared reasoning, task-specific context assembly, and agent coordination. Start by installing the Twining command-line tool, configure your MCP client to connect to the local server, and then use the available tools to post findings, assemble context, record decisions, and inspect the knowledge graph and dashboard.

How to install

Prerequisites you need before installing are Node.js version 18 or newer and npm. You will install the Twining MCP CLI globally, then run the MCP server locally within your project.

npm install -g twining-mcp

Configuration and operation

Configure your MCP client to connect to the Twining server by specifying the MCP server in your client settings. You can point the client to a local project context or a dedicated project path. The server exposes a dashboard on a configurable port for browsing blackboard entries, decisions, the knowledge graph, and agent coordination state.

To run the server locally, start the Twining MCP command with your project path. The following configuration snippet shows the recommended runtime configuration for a local setup.

{
  "mcpServers": {
    "twining": {
      "command": "twining-mcp",
      "args": ["--project", "/path/to/your/project"]
    }
  }
}

Note: If you omit --project, Twining uses the current working directory.

## Dashboard and local state

The embedded web dashboard starts automatically and is reachable on port 24282 by default. You can customize it via the TWINING\_DASHBOARD\_PORT environment variable. Open http://localhost:24282 to browse the blackboard, decision timeline, knowledge graph, and agent coordination views.

## Additional usage notes

All state is stored in a .twining/ directory at your project root. The server uses a layered architecture to manage storage, business logic, embeddings, the dashboard, and tooling. You can query, inspect, and export the full state as needed for auditing or sharing tacit knowledge across teams.

## Troubleshooting

If the dashboard does not start, verify that Node.js 18+ is installed and that you launched the CLI with the correct project path. Check that the .twining/ directory is writable and that you do not have permission issues on your project folder. If embedding model loading fails, the server will continue to operate with keyword search fallback.

## Available tools

### twining\_post

Post an entry (finding, need, warning, question) to the shared blackboard

### twining\_read

Read blackboard entries with optional filters by type, scope, or agent

### twining\_query

Semantic search across blackboard entries, with keyword fallback

### twining\_recent

Get the most recent blackboard entries

### twining\_decide

Record a decision with rationale, alternatives, and traceability

### twining\_why

Retrieve all decisions affecting a given scope or file

### twining\_trace

Trace a decision's dependency chain upstream and/or downstream

### twining\_reconsider

Flag a decision for reconsideration with downstream impact analysis

### twining\_override

Override a decision with a reason, optionally creating a replacement

### twining\_search\_decisions

Search decisions by keyword or semantic similarity with filters

### twining\_link\_commit

Link a git commit hash to an existing decision

### twining\_commits

Query decisions by git commit hash

### twining\_assemble

Build tailored context for a task within a token budget

### twining\_summarize

Get a high-level summary of project state and activity

### twining\_what\_changed

Report what changed since a given point in time

### twining\_status

Overall health check — entry counts, agent counts, warnings, and summary

### twining\_archive

Archive old blackboard entries to reduce working set size

### twining\_export

Export full Twining state as a single markdown document

### twining\_add\_entity

Add or update a knowledge graph entity (upsert semantics)

### twining\_add\_relation

Add a relation between two knowledge graph entities

### twining\_neighbors

Traverse the knowledge graph from an entity up to depth 3

### twining\_graph\_query

Search the knowledge graph by name or property substring

### twining\_agents

List registered agents with capabilities, liveness status, and filtering

### twining\_discover

Find agents matching required capabilities, ranked by overlap and liveness

### twining\_delegate

Post a delegation request to the blackboard with capability requirements

### twining\_handoff

Create a handoff between agents with work results and auto-assembled context

### twining\_acknowledge

Acknowledge receipt of a handoff