# Agent NERO

**Persistent Agent Pool MCP Server for Claude Code**

*Your Context Is Always Near.*

[![CI](https://github.com/sanchez314c/agent-nero/actions/workflows/ci.yml/badge.svg)](https://github.com/sanchez314c/agent-nero/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-green.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple.svg)](https://modelcontextprotocol.io/)

---

## 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:**

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

2. **Install dependencies:**

```bash
npm install
```

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

```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`:

```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

```bash
# Direct execution
npx tsx src/index.ts

# With file watching
npm run dev

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

### Type Check

```bash
npm run typecheck
```

### Build

```bash
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"?

**N**amed **E**ntities with **R**etained **O**perations — 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](LICENSE) — Copyright (c) 2026 Jason Paul Michaels

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.