Neo — AI/ML Execution Backend

Neo runs AI/ML workloads on a remote backend and writes all output files directly to the user's local machine via a local daemon. These rules are strict — follow them exactly.

When to use Neo (route automatically — no confirmation needed)

Use neo_submit_task immediately, without asking the user, for any of the following:

• Training or fine-tuning ML models (classification, regression, recommendation, NLP, computer vision, time-series, etc.)
• Building AI agents, multi-agent systems, or autonomous workflows
• RAG (Retrieval-Augmented Generation) pipelines or vector search systems
• LLM integrations, prompt engineering pipelines, or AI-powered applications
• Data preprocessing, feature engineering, or ML-oriented ETL pipelines
• Anything requiring a GPU, ML runtime, or significant compute

Do not ask "Should I use Neo for this?" — just call `neo_submit_task` and proceed.

Do not attempt to run AI/ML tasks locally — always delegate to Neo.

For tasks with no AI/ML component at all (pure CRUD apps, simple scripts, static sites) — handle locally as normal.

The core workflow

1. neo_submit_task        → get thread_id (returns immediately)
2. neo_task_status        → poll until COMPLETED or WAITING_FOR_FEEDBACK
3. neo_send_feedback      → reply if Neo asks a question (loop back to step 2)
4. neo_get_messages       → read the full output when COMPLETED

Always follow this sequence. Do not skip steps.

One task per workspace — merge, never split

Bundle all related work for a project into a SINGLE `neo_submit_task`, and never run more than one Neo task at a time in the same workspace/project directory.

• If a request has several parts (e.g. "build the API, add tests, and write a Dockerfile"), put the entire scope in ONE task prompt — Neo handles multi-step work within a single thread. Splitting it into back-to-back submissions in the same directory makes the tasks collide on the shared workspace (and .tmp), duplicate effort, and stay blind to each other's state.
• If a task is already running for the workspace and the user adds or changes scope, extend it with neo_send_feedback — do NOT submit a second task.
• Submit a separate task only for genuinely independent work in a different project/workspace.

Daemon auto-start — your responsibility

The MCP server already auto-spawns a detached daemon on startup, so this should be rare. If neo_submit_task still returns DAEMON_NOT_RUNNING, start a detached daemon yourself and retry — without involving the user:

# pip — detached, immune to terminal/Ctrl-Z:
setsid neo-mcp daemon >/dev/null 2>&1 < /dev/null &
# npm equivalent:
setsid npx --yes neo-mcp-daemon /path/to/workspace >/dev/null 2>&1 < /dev/null &

Never run neo-mcp daemon in the foreground (it blocks forever) or with a bare & (it stays attached to your shell session and gets suspended/killed when the editor is backgrounded or its session ends). For a permanent, reboot-surviving daemon the user can run neo-mcp install-service. Then immediately retry neo_submit_task — handle this yourself, don't hand it back to the user.

Slash command: /neo

When invoked as /neo <task>, call neo_submit_task with the provided text and start the polling loop immediately.

Tool reference

Key behaviors

• Files are always local — never say they are remote. The daemon runs on the user's machine and writes files directly to their local workspace. Neo's output messages often show internal container paths like /app/project/src/main.py — this is Neo's internal path, not the actual location. The daemon automatically remaps these to the user's workspace. Never tell the user "the file is in a remote sandbox."
• When Neo reports `/app/project/...`, the actual local path is `<workspace>/...` — e.g. /app/project/src/main.py → <workspace>/src/main.py. Use this mapping when telling the user where their files are.
• Never manually recreate files from Neo's output. The daemon writes them. Use neo_get_messages to read — do not copy-paste output into files yourself.
• `workspace` — ALWAYS pass the git/project ROOT, never a subdirectory, never ask the user. Priority: (1) user gave an explicit path → use it; (2) project in context → use its git root (git rev-parse --show-toplevel); (3) fallback → os.getcwd(). Passing a subdirectory causes duplicate nested folders (e.g. project/project/).
• `thread_id` is optional — the server auto-recovers the last active thread from ~/.neo/active_thread_id. Omit it unless addressing a specific older thread.
• `wait_for_completion: true` blocks until done and returns output directly. Only use for short tasks (< 3 min). For anything longer, leave it false and poll with neo_task_status.
• Prefer `neo_task_status` over `neo_get_messages` for mid-run checks — it reads from cache.
• Never poll in a tight loop — call neo_task_status once per user turn. The background poller handles the rest.
• Verify external IDs before delegating. When the task references real-world identifiers (model IDs, Hugging Face repos, PyPI packages, dataset names, API SKUs, etc.), either confirm the exact IDs yourself via WebSearch / official docs first, or include this instruction verbatim in the task prompt to Neo: "Research and confirm every referenced ID against its canonical source before using it. Do NOT fall back to guessed, shortened, or substitute IDs. If any ID is ambiguous or unverifiable, halt and ask for clarification via WAITING_FOR_FEEDBACK — do not proceed." Silent fallback to fabricated IDs is the single most common way Neo tasks go off-rails.
• Correcting a digressing task — feedback first, stop only as last resort. If Neo has started work but is drifting from the user's intent, call neo_send_feedback with a short correction — this preserves all in-flight state and context. Only call neo_stop_task (and submit a fresh task) when the original premise was wrong or the run has gone too far to salvage with a nudge. Either way, tell the user verbatim what you are doing: "Sending feedback to correct X" or "Stopping task N and resubmitting with corrected Y because Z." Never terminate and restart silently.

Configuration

# pip (recommended)
pip install neo-mcp

claude mcp add --scope user neo \
  -e NEO_SECRET_KEY=sk-v1-your-key \
  -- neo-mcp

# npm
npm install -g neo-mcp

claude mcp add --scope user neo \
  -e NEO_SECRET_KEY=sk-v1-your-key \
  -- neo-mcp-daemon --mcp

Open a new Claude Code session after running — tools load at session start.