@propstreet/agenthub
Advanced tools
Lean MCP Orchestrator for Multi-Agent Coordination
AgentHub is a lightweight, local-only MCP (Model Context Protocol) server that enables multiple coding agents (Claude Code, Cursor, VS Code, etc.) to coordinate edits, reviews, and escalations without file locking conflicts.
# Clone the repository
git clone https://github.com/propstreet/agenthub.git
cd agenthub
# Install dependencies
npm install
# Build the project
npm run build
# Start the server
npm start
The server will start on http://localhost:3333 by default.
.env.example to .env:cp .env.example .env
.env and configure:# Server Configuration
PORT=3333
HOST=localhost
# Logging (info = quiet, debug = verbose HTTP logs)
LOG_LEVEL=info
# Filesystem Watcher (optional)
WATCH_ROOT=/path/to/your/project
# Persistence (optional)
PERSISTENCE_ENABLED=true
PERSISTENCE_PATH=.agenthub/state.json
PERSISTENCE_INTERVAL=60000
PERSISTENCE_AUTO_RESTORE=true
# Azure OpenAI for Expert Escalation (optional)
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_EXPERT_DEPLOYMENT=gpt-5-pro
Claude Code - Add to claude_desktop_config.json:
{
"mcpServers": {
"agenthub": {
"url": "http://localhost:3333/mcp"
}
}
}
VS Code - Add to MCP settings:
{
"mcp.servers": [
{
"name": "agenthub",
"url": "http://localhost:3333/mcp"
}
]
}
Monitor agents, intents, and messages in real-time:
npm run dashboard
The dashboard shows:
┌─────────────┐
│ Agents │ (Claude Code, Cursor, VS Code, etc.)
└──────┬──────┘
│ HTTP (Streamable MCP)
├─────────────────┐
│ AgentHub │
│ ┌───────────┐ │
│ │ hub_op │ │ Multi-operation tool (14 ops)
│ ├───────────┤ │
│ │ Resources │ │ inbox://, state://
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Core │ │ Bus, Coordinator, Watcher, Persistence
│ └───────────┘ │
└─────────────────┘
hub_op ToolAll operations go through a single multi-operation tool:
{
"op": "<operation>", // operation code
"d": { ... } // operation payload
}
Get help on available operations:
{
"op": "s.help",
"d": {}
}
{
"op": "a.register",
"d": {
"agent": "my-agent",
"role": ["developer", "reviewer"]
}
}
Note: agent field is auto-generated if omitted.
Open Intent (declare work):
{
"op": "i.open",
"d": {
"paths": ["src/server/**/*.ts"],
"mode": "W",
"priority": "n",
"ttlMs": 120000
}
}
Vote on Intent:
{
"op": "i.vote",
"d": {
"intentId": "intent_abc123",
"vote": "approve"
}
}
Renew Intent (heartbeat):
{
"op": "i.renew",
"d": {
"intentId": "intent_abc123",
"ttlMs": 120000
}
}
Close Intent:
{
"op": "i.close",
"d": {
"id": "intent_abc123",
"status": "ok",
"note": "Changes complete"
}
}
Send Message:
{
"op": "m.send",
"d": {
"to": "agent-2",
"text": "Ready to review your changes",
"topic": "review"
}
}
Pull Messages:
{
"op": "m.pull",
"d": {
"since": 1731340000000,
"limit": 50
}
}
Request Review:
{
"op": "review.request",
"d": {
"scope": ["src/auth/**/*.ts"],
"summary": "Please review authentication changes"
}
}
Claim Review (requires reviewer role):
{
"op": "review.claim",
"d": {
"jobId": "rev_abc123"
}
}
Complete Review:
{
"op": "review.complete",
"d": {
"jobId": "rev_abc123",
"severity": "warning",
"notes": "Consider adding error handling for edge cases",
"patch": "--- a/src/auth.ts\n+++ b/src/auth.ts\n..."
}
}
Ask Expert (requires Azure OpenAI configuration):
{
"op": "expert.ask",
"d": {
"paths": ["src/complex-algorithm.ts"],
"question": "How can I optimize this for performance?"
}
}
Get State:
{
"op": "s.get",
"d": {
"filter": "intents"
}
}
inbox://{agent} - Agent message queue (NDJSON format)
state://live - Complete state snapshot (JSON)
AgentHub supports field name variants for flexibility:
| Canonical | Variants |
|---|---|
agent | from |
paths | p |
mode | m |
priority | prio |
ttlMs | ttl |
text | msg |
to | target |
The agent field is auto-populated from your MCP session context when omitted.
R - Read (viewing files only)W - Write (editing files)B - Build (compiling project)T - Test (running tests)l - Low (can be preempted)n - Normal (default)h - High (important task)r - Review (code review priority)Resolution order: r > h > n > l
Phase 1 - Declare
i.open with paths and modePhase 2 - Execute
i.renew every 60-90sPhase 3 - Close
i.close when done# Development
npm run dev # Start with auto-reload (tsx watch)
npm run dashboard # Launch terminal dashboard
# Build
npm run build # Build TypeScript to dist/
# Quality
npm run typecheck # Type check without emitting
npm run lint # Lint code with ESLint
npm run lint:fix # Fix linting issues
npm run format # Format code with Prettier
npm run check # Run all checks (type + lint + format)
# Testing
npm test # Run all tests with vitest
agenthub/
├── src/
│ ├── server/
│ │ ├── core/ # Core logic (bus, coordinator, watcher, persistence)
│ │ ├── tools/ # hub_op operation handlers
│ │ ├── resources/ # MCP resource handlers
│ │ ├── schemas/ # Zod validation schemas
│ │ ├── transports/ # HTTP transport layer
│ │ ├── types/ # TypeScript models
│ │ ├── server.ts # MCP server setup
│ │ └── index.ts # Entry point
│ └── dashboard/ # Terminal UI (Ink v5)
├── .agenthub/ # State snapshots (gitignored)
├── .mcp-config/ # Client configuration examples
├── .env.example # Environment template
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # MIT license
└── README.md # This file
AgentHub is designed to minimize token overhead:
Typical operation: ≤60 tokens (payload only)
We welcome contributions from the community! Please see CONTRIBUTING.md for guidelines.
Quick Contribution Steps:
npm run check to verifyFor security issues, please see SECURITY.md for our security policy and how to report vulnerabilities.
MIT © Propstreet
Built with:
FAQs
Lean MCP orchestrator for coordinating multiple coding agents
The npm package @propstreet/agenthub receives a total of 7 weekly downloads. As such, @propstreet/agenthub popularity was classified as not popular.
We found that @propstreet/agenthub demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GitHub Actions now supports cache-mode, a least-privilege control on the Actions cache aimed at the cache poisoning technique behind recent compromises.
Company News
Allow myself to introduce... myself.
Research
/Security News
A Twitch browser extension on Chrome and Firefox forwards users’ live OAuth session tokens through proxies controlled by a Russian bot service.