Nod CLI
Open source CLI for running AI coding agents as persistent daemons with mobile control
Overview
The Nod CLI is an open source tool that wraps AI coding agents into persistent, mobile-controlled daemons. It handles background persistence, tool permissions via mobile approval, per-agent isolation, and scheduled tasks.
What it solves
Running multiple AI coding agents in production is hard without isolation and control. The Nod CLI solves the key challenges:
| Challenge | How Nod CLI solves it |
|---|---|
| No per-agent isolation — all sessions share the same config, MCPs, and permissions | Each agent gets its own MCP servers, skills, subagents, permissions, memory, and instructions — fully enforced at runtime |
| Background agents need persistent tool permissions | Async mobile approval via the Nod app. Permission patterns persist across restarts in per-agent settings files |
| No structured way to define scoped agent roles | nod connect creates isolated agent profiles with resource scoping — the developer gets GitHub, the assistant gets Gmail |
| Remote control is limited to basic conversations | Full mobile experience: chat, tool approvals, per-agent activity feed, scheduled tasks, and resource management |
| Background agents can die or lose session state | OS-level daemons via launchd/systemd with auto-restart, session persistence, and sleep prevention |
How it works
- The CLI connects to Nod via WebSocket and stays connected while Claude Code runs.
- Claude Code's
PreToolUsehooks route every tool call through Nod's permission gate. Each call is checked against allow/deny rules before execution. - Tools that aren't pre-approved generate a permission card in the Nod app. The user taps Allow, Always Allow, or Deny from their phone.
- Users can chat with Claude Code from the app — send instructions, ask questions, or provide context.
- Activity logging tracks what Claude is doing — files read, edits made, commands run.
- Tasks run in parallel with the main conversation, each in their own isolated session.
Getting started
Install the CLI
curl -fsSL https://asknod.ai/install.sh | bash
Create an agent in the Nod app
Open the Nod app on your phone. Create a new agent — you'll get an Agent ID and Secret.
Open the CLI menu
nod
Running nod without arguments opens the interactive menu. From here you can connect agents, start/stop them, view logs, configure resources, and more — all from one place.
Connect an agent
Select connect from the menu. The interactive wizard detects your project's resources (MCP servers, skills, subagents) and lets you configure which resources this agent can access and which tools to auto-approve.
Start the agent
Select up from the menu and pick your agent. It starts as a background daemon. Close your terminal — you're now working from your phone.
Per-agent isolation
Every Nod agent is a fully isolated Claude Code environment. During nod connect, you define exactly what each agent can access — like an AGENTS.md but managed through the CLI and enforced at runtime via hooks.
| Isolation layer | How it works |
|---|---|
| MCP servers | Each agent only sees its assigned MCPs. The assistant gets Gmail; the developer gets GitHub. Trying to use an unassigned MCP returns a clear error, not a permission prompt. |
| Skills & subagents | Agents only see skills and subagents enabled for them during setup |
| Permission rules | Per-agent settings file (settings.nod-<agent>.json) — auto-approve shell commands for the developer, require approval for the assistant |
| Instructions | Custom system prompt per agent at ~/.nod/agents/<name>/instructions.md |
| Memory | Persistent memory file per agent at ~/.nod/agents/<name>/memory.md |
| Context window | Each agent is a separate Claude Code process — no shared token budget |
Multi-agent setup
Run multiple agents simultaneously, each with its own scoped resources:
# Connect each agent with different resource access nod connect # → "assistant" with Gmail, Calendar, Notion nod connect # → "developer" with Supabase, GitHub nod connect # → "creative" with image generation, web search # Start them all as background daemons nod up assistant nod up developer nod up creative # Check status nod ps
Daemon mode
nod up starts the agent as a background daemon managed by the OS. Select up from the nod menu and pick an agent:
| Feature | Nod CLI daemon |
|---|---|
| Lifetime | Runs indefinitely via launchd (macOS) / systemd (Linux) |
| Auto-restart | KeepAlive (macOS), Restart=always (Linux) — recovers from crashes |
| Survives reboot | Yes — RunAtLoad (macOS) |
| Sleep prevention | caffeinate -i keeps Mac awake while agent runs |
| Session persistence | Session map saved to disk, resumes on restart |
| Tool permissions | Async mobile approval via Nod app, waits indefinitely |
| Agent isolation | Each daemon is a separate process with its own config |
Permission system
Every tool call goes through a five-step permission gate:
| Step | Check | Result |
|---|---|---|
| 1 | Deny list | Block immediately if tool matches a deny rule |
| 2 | Auto-allow | Always allow internal Nod tools (nod-request, nod-activity, etc.) |
| 3 | Agent scope | Block if tool uses a resource not enabled for this agent |
| 4 | Allow list | Allow if tool matches a pre-approved pattern (e.g. Bash(npm install *)) |
| 5 | Mobile approval | Send permission card to Nod app and wait for user response |
When a user taps Always Allow, the pattern is saved to the agent's settings file. The permission persists across sessions and restarts — no more re-prompting every session.
Scheduled tasks
Tasks are like cron jobs for your agent. Define what to do and when:
# Examples of tasks: "Check my emails and summarize" → every weekday at 9am "Generate a daily news digest" → every morning at 7am "Run tests and report failures" → every 6 hours "Summarize yesterday's git activity" → every weekday at 9am
Tasks can be created from the app or proposed by the agent during chat. Each task runs in its own session, in parallel with the main conversation.
Agent tools
| Tool | Purpose |
|---|---|
| nod-request | Ask the user for a decision (choice, question, or approval) |
| nod-activity | Log an action to the activity feed |
| nod-report | Send a structured markdown document (tappable card) |
| nod-task-create | Propose a scheduled or recurring task |
| nod-task-output | Set the final deliverable for a task run |
| nod-task-run | Fetch a previous task run’s output |
| nod-image | Send an image to the user (inline in chat) |
--append-system-prompt-file, so they only exist inside Nod-spawned Claude sessions. Your regular claude sessions in the same project are completely clean.Commands
Run nod to open the interactive menu, or use commands directly:
| Command | Description |
|---|---|
| nod | Open the interactive menu (recommended) |
| nod connect | Set up agent credentials, detect resources, configure permissions |
| nod up <agent> | Start agent as a background daemon |
| nod down <agent> | Stop a background agent |
| nod start <agent> | Run agent in the foreground (for debugging) |
| nod ps | List all agents with status |
| nod logs <agent> | View agent logs |
| nod rm <agent> | Remove agent |
| nod config <agent> | Interactive config menu |
| nod doctor [agent] | Run diagnostics |
Source code
The CLI is fully open source:
| File | What it does |
|---|---|
| src/daemon.ts | Background daemon — caffeinate, lifecycle, graceful shutdown |
| src/core/nod-client.ts | WebSocket connection, heartbeat, auto-reconnect |
| src/core/hook-server.ts | HTTP server for PreToolUse hooks and nod-tool scripts |
| src/core/permission-gate.ts | Five-step permission gate with scope enforcement |
| src/core/claude-adapter.ts | Claude Code subprocess management, per-agent settings |
| src/core/task-scheduler.ts | Task polling + real-time WebSocket triggers |