Agent NERO

Persistent Agent Pool MCP Server for Claude Code

Your Context Is Always Near.

---

What Is Agent NERO?

Agent NERO is an MCP (Model Context Protocol) server that gives Claude Code the ability to spawn, manage, and communicate with persistent, named LLM agents that stay alive in memory for the duration of your session.

Unlike Claude Code's built-in subagents (which are fire-and-forget — spawned, used once, destroyed), NERO agents:

• Persist — They stay alive in RAM with full conversation history
• Remember — Each agent maintains its own conversation context across multiple interactions
• Use tools — Agents can read/write files, search code, run commands, and interact with the filesystem
• Collaborate — A shared memory bus lets agents publish findings that other agents (and you) can read
• Specialize — Each agent has its own role, system prompt, model selection, and tag-based filtering

Zero modifications to Claude Code source required. NERO runs as a standard MCP server over stdio transport.

Architecture

Claude Code (Host)
    │
    ├── nero_spawn  ──→  AgentPool.spawn()  ──→  NeroAgent(config, apiKey, memoryBus)
    ├── nero_ask    ──→  AgentPool.get()    ──→  NeroAgent.ask(message)
    │                                              │
    │                                              ├── Anthropic API (tool-use loop, max 15 iterations)
    │                                              │     ├── read_file
    │                                              │     ├── write_file
    │                                              │     ├── list_files
    │                                              │     ├── search_files
    │                                              │     ├── run_command
    │                                              │     ├── memory_read
    │                                              │     └── memory_write
    │                                              │
    │                                              └── History (sliding window, token budget)
    │
    ├── nero_broadcast ──→ AgentPool.broadcast() ──→ All agents concurrently
    ├── nero_status     ──→ AgentPool.getStatus()
    ├── nero_memory_*   ──→ MemoryBus (shared key-value store)
    ├── nero_kill       ──→ AgentPool.kill()
    ├── nero_reset      ──→ AgentPool.reset()
    └── nero_configure  ──→ NeroAgent.updateConfig()

Installation

Prerequisites

• Node.js >= 20.0.0
• Claude Code CLI installed and configured
• Anthropic API key (with access to Claude Opus/Sonnet)

Setup

1. Clone the repository:

git clone https://github.com/sanchez314c/agent-nero.git
cd agent-nero

2. Install dependencies:

npm install

3. Register as MCP server — Add to your ~/.mcp.json:

{
  "mcpServers": {
    "nero": {
      "command": "npx",
      "args": ["tsx", "/path/to/agent-nero/src/index.ts"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Allow MCP tools — Add to ~/.claude/settings.local.json:

{
  "enabledMcpjsonServers": ["nero"],
  "permissions": {
    "allow": [
      "mcp__nero__nero_spawn",
      "mcp__nero__nero_ask",
      "mcp__nero__nero_broadcast",
      "mcp__nero__nero_status",
      "mcp__nero__nero_memory_write",
      "mcp__nero__nero_memory_read",
      "mcp__nero__nero_memory_dump",
      "mcp__nero__nero_kill",
      "mcp__nero__nero_reset",
      "mcp__nero__nero_configure"
    ]
  }
}

5. Restart Claude Code to pick up the new MCP server.

Verify Installation

In a Claude Code session, the NERO tools should appear when you run /mcp. You can test with:

Use nero_spawn to create an agent named "test" with role "test agent"

Usage

Spawn an Agent

nero_spawn:
  name: "architect"
  role: "Senior software architect"
  system_prompt: "You are a senior software architect. Analyze code structure, identify patterns, and propose improvements."
  model: "sonnet"
  tags: ["analysis", "architecture"]

Ask an Agent

nero_ask:
  agent: "architect"
  message: "Review the authentication flow in src/auth/ and identify any security concerns."
  include_memory: false

The agent will use its tools (read files, search code, run commands) to investigate and respond. Its conversation history persists — you can ask follow-up questions that reference prior answers.

Broadcast to All Agents

nero_broadcast:
  message: "Summarize your findings so far."
  tags: ["analysis"]
  collect_responses: true

Shared Memory Bus

Agents can share findings through the memory bus:

nero_memory_write:
  key: "findings.auth"
  value: "JWT tokens are not validated for expiry in the /api/admin routes."

nero_memory_read:
  prefix: "findings"

Agent Lifecycle

nero_status                    # Pool overview
nero_status agent:"architect"  # Detailed agent status
nero_configure agent:"architect" model:"opus"  # Switch model at runtime
nero_reset agent:"architect"   # Clear history, keep agent alive
nero_kill agent:"architect"    # Terminate permanently

Export Memory to Disk

nero_memory_dump:
  prefix: "findings"
  output_path: "/path/to/memory_snapshot.json"

MCP Tools Reference

Tool	Description
nero_spawn	Create a new named persistent agent
nero_ask	Send a message to an agent, receive response
nero_broadcast	Message all agents (or filtered by tags)
nero_status	Pool overview or detailed agent status
nero_memory_write	Write to shared memory bus
nero_memory_read	Read from shared memory bus
nero_memory_dump	Export memory entries to JSON file
nero_kill	Terminate an agent permanently
nero_reset	Clear agent history, keep it alive
nero_configure	Update agent config at runtime

Agent Internal Tools

Each agent has access to 7 tools via the Anthropic tool-use protocol:

Tool	Description
read_file	Read file contents from disk
write_file	Write/create files (creates parent dirs)
list_files	Glob-based file discovery
search_files	Grep-based content search with regex
run_command	Execute shell commands (30s timeout, destructive commands blocked)
memory_read	Read from shared memory bus
memory_write	Write to shared memory bus

Configuration

Agent Defaults

Setting	Default	Range
Model	sonnet	opus, sonnet
Max history messages	50	4 – 200
Max tokens per response	8192	256 – 32768
Tool-use loop iterations	15	Fixed
Token budget (history)	100,000	Fixed

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Anthropic API key for agent LLM calls

Development

Run from Source

# Direct execution
npx tsx src/index.ts

# With file watching
npm run dev

# Using the run script
./run-source-linux.sh

Type Check

npm run typecheck

Build

npm run build

Project Structure

agent-nero/
├── src/
│   ├── index.ts          # Entry point — MCP server + transport
│   ├── types.ts          # All TypeScript interfaces and types
│   ├── memory-bus.ts     # Shared key-value memory store
│   ├── agent.ts          # NeroAgent class — tool-use loop, history management
│   ├── agent-pool.ts     # Agent lifecycle management
│   ├── agent-tools.ts    # 7 internal tool definitions + executors
│   └── tools/
│       ├── spawn.ts      # nero_spawn MCP handler
│       ├── ask.ts        # nero_ask MCP handler
│       ├── broadcast.ts  # nero_broadcast MCP handler
│       ├── status.ts     # nero_status MCP handler
│       ├── memory-write.ts  # nero_memory_write MCP handler
│       ├── memory-read.ts   # nero_memory_read MCP handler
│       ├── memory-dump.ts   # nero_memory_dump MCP handler
│       ├── kill.ts       # nero_kill MCP handler
│       ├── reset.ts      # nero_reset MCP handler
│       └── configure.ts  # nero_configure MCP handler
├── docs/
│   ├── README.md        # Documentation index
│   ├── QUICK_START.md   # 5-minute setup guide
│   ├── ARCHITECTURE.md  # System architecture deep-dive
│   ├── INSTALLATION.md  # Setup and configuration guide
│   ├── DEVELOPMENT.md   # Development workflow and standards
│   ├── BUILD_COMPILE.md # Build system and compilation
│   ├── DEPLOYMENT.md    # Deployment and release process
│   ├── API.md           # Complete API documentation
│   ├── FAQ.md           # Frequently asked questions
│   ├── TROUBLESHOOTING.md # Common issues and solutions
│   ├── TECHSTACK.md     # Technology stack breakdown
│   ├── WORKFLOW.md      # Development workflow
│   ├── LEARNINGS.md     # Development lessons and patterns
│   ├── PRD.md           # Product requirements
│   └── TODO.md          # Known issues and planned features
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   ├── workflows/
│   │   └── ci.yml
│   └── PULL_REQUEST_TEMPLATE.md
├── package.json
├── tsconfig.json
├── run-source-linux.sh
├── LICENSE
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CLAUDE.md
├── AGENTS.md
├── VERSION_MAP.md
└── CHANGELOG.md

Why "NERO"?

Named Entities with Retained Operations — persistent agents that remember, specialize, and collaborate. Unlike disposable subagents that vanish after one use, NERO agents are your standing team: always alive, always context-aware, always near.

License

MIT — Copyright (c) 2026 Jason Paul Michaels

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for reporting vulnerabilities.