io.github.eidetic-works/nucleus

Boot an external agent into the Nucleus Agent OS for one turn. The OS recalls memory, mediates the model call, labels the response with a referee verdict, and records the turn. Stage 4 platform primitive.

Agent spawning, critic, swarm, memory, ingestion & dashboard tools. Actions: spawn_agent - Spawn Ephemeral Agent. params: {intent, execute_now?, persona?, confirm?}. HITL: requires confirm=true. apply_critique - Apply critique fixes. params: {review_path} orchestrate_swarm - Start multi-agent swarm. params: {mission, agents?} search_memory - Search long-term memory. params: {query} read_memory - Read memory category. params: {category} respond_to_consent - Respond to respawn consent. params: {agent_id, choice?} list_pending_consents - List agents awaiting consent critique_code - Run Critic review. params: {file_path, context?} fix_code - Auto-fix code. params: {file_path, issues_context} session_briefing - Get session briefing. params: {conversation_id?} register_session - Register session focus. params: {conversation_id, focus_area, role?, tier?, charter_path?, parent_session?}. Tier ∈ {opus,sonnet,haiku}; role must start with tier prefix. handoff_task - Hand off task. params: {task_description, target_session_id?, priority?} ingest_tasks - Ingest tasks. params: {source, source_type?, session_id?, auto_assign?, skip_dedup?, dry_run?} rollback_ingestion - Rollback ingestion. params: {batch_id, reason?} ingestion_stats - Get ingestion statistics dashboard - Enhanced dashboard. params: {detail_level?, format?, include_alerts?, include_trends?, category?} snapshot_dashboard - Create dashboard snapshot. params: {name?} list_dashboard_snapshots - List snapshots. params: {limit?} get_alerts - Get active alerts set_alert_threshold - Set alert threshold. params: {metric, level, value}

W8 Team-tier tamper-evident audit log (SHA-256 hash chain). Actions: log_event - Append an audit event to the chain. params: {event_type, actor, resource, outcome, metadata?, team_id?, ts?} query - Single-tenant query. Rejects team_id='*'. params: {team_id, since?, until?, actor?, event_type?, limit?, offset?} admin_query - Cross-tenant query (team_id='*' allowed). Requires NUCLEUS_AUDIT_ADMIN_TOKEN env match. Logs every successful call to the synthetic '__admin__' chain. params: {admin_token, team_id?, since?, until?, actor?, event_type?, limit?, offset?} verify - Verify SHA-256 chain integrity for a team. params: {team_id}

One-shot convenience: resolve canonical inbox + arm long-poll subscription. Per PR #2 (CCR server-side auto-arm) — IDE-agnostic relay-arrival arming. This is the RECOMMENDED entry point for SessionStart auto-arming across all MCP clients (Claude Code, Antigravity, Cursor, Windsurf, etc.). Equivalent to: 1. resolve_canonical_inbox_name(role) → canonical inbox name 2. nucleus_relay_subscribe(inbox_filter=<canonical>, timeout_seconds=...) Why this exists vs nucleus_relay_subscribe + inbox_filter: nucleus_relay_subscribe + inbox_filter requires the caller to KNOW the canonical inbox name for their role. nucleus_ccr_arm hides that step. Agent just calls nucleus_ccr_arm() with no args; server detects role from CC_SESSION_ROLE / NUCLEUS_SESSION_ROLE env OR detect_session_role().

Hand a coding or review task to a cross-vendor lane — a cheap, non-Claude agent that does the work for you. Use this INSTEAD OF shelling out to any CLI: it picks the vendor, injects the correct per-vendor permission flags, captures all output synchronously, and reports a real status. Do NOT run `agy`/`devin` yourself in Bash — the raw CLIs take DIFFERENT per-vendor flags (pass the wrong one and a build silently makes ZERO edits yet exits 0), and hand-driven background calls flush output late (a finished call looks empty for tens of seconds). This tool is the only robust path. First call `list` — it needs no setup, confirms cross-vendor is enabled, and shows each vendor's selectable_models + default_model. If dispatch/review return a disabled error, cross-vendor is OFF: run `nucleus onboard` once (one-time), then retry. Actions: dispatch - Hand a task to a cross-vendor lane. params: {vendor, prompt, artifact_ref, mode?, model?, expect_paths?, to?, timeout_s?} REQUIRED: vendor ∈ 'agy'|'devin', prompt, artifact_ref. mode ∈ 'write'|'read' (default 'write'): write = the vendor CHANGES things (edit files, run commands, build/fix). read = the vendor only LOOKS and REPORTS (analyze/summarize); no file changes. When unsure use 'write': a read task still works in write mode, but a write task silently does NOTHING in read mode. model? — optional. Defaults to the vendor's verified model (agy → gemini-3.8-flash-high, devin → swe-2-max). These are ALREADY the defaults, so omitting model is sufficient; pass it only to be explicit or to override; pass "glm-5-2" to use GLM-5.2 High instead. The response echoes model_id — read model_id (NOT model_family) to confirm which model ran. A cross-wired model (e.g. glm-5-2 with agy) is rejected with the valid ids named. artifact_ref — a commit SHA / PR# / file path to bind the result to. No commit yet (a from-scratch bu…

Engrams, health, observability, DSoR & tier system tools. Actions: health - Get system health status version - Get Nucleus version info export_schema - Export MCP toolset as JSON Schema performance_metrics - Get perf metrics. params: {export_to_file?} prometheus_metrics - Get Prometheus metrics. params: {format?} audit_log - View cryptographic interaction log. params: {limit?} write_engram - Write engram to memory. params: {key, value, context?, intensity?}. context: Feature|Architecture|Brand|Strategy|Decision. intensity: 1-10. (alias: "add") query_engrams - Query engrams. params: {context?, min_intensity?, limit?}. limit default 50, max 500. search_engrams - Search engrams. params: {query, case_sensitive?, limit?}. limit default 50, max 500. (alias: "search") governance_status - Get governance status morning_brief - Daily Nucleus Morning Brief hook_metrics - Monitor auto-write engram hooks compounding_status - Compounding Loop status end_of_day - Capture EOD learnings. params: {summary, key_decisions?, blockers?} session_inject - Session-start context injection weekly_consolidate - Weekly consolidation. params: {dry_run?} list_decisions - List DecisionMade events. params: {limit?} list_snapshots - List context snapshots. params: {limit?} metering_summary - Token metering summary. params: {since_hours?} ipc_tokens - List IPC auth tokens. params: {active_only?} dsor_status - Comprehensive DSoR status pulse_and_polish - God Combo: automated health check pipeline. params: {write_engram?}. Runs prometheus→audit→brief→engram. self_healing_sre - God Combo: SRE diagnosis pipeline. params: {symptom, write_engram?}. Runs search→metrics→diagnose→recommend. fusion_reactor - God Combo: self-reinforcing memory loop. params: {observation, context?, intensity?, write_engrams?}. Compounds knowledge.…

Feature tracking, proof generation & MCP server mounting. Actions: add - Add a feature. params: {product, name, description, source, version, how_to_test, expected_result, status?, tags?} list - List features. params: {product?, status?, tag?} get - Get feature by ID. params: {feature_id} update - Update feature fields. params: {feature_id, status?, description?, version?} validate - Mark feature validated. params: {feature_id, result} search - Search features. params: {query} mount_server - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] Mount external MCP server. params: {name, command, args?} thanos_snap - Trigger Instance Fractal Aggregation unmount_server - Unmount MCP server. params: {server_id} list_mounted - List mounted MCP servers discover_tools - Discover tools from mounted servers. params: {server_id?} invoke_tool - Invoke tool on mounted server. params: {server_id, tool_name, arguments?} traverse_mount - Recursively mount downstream servers. params: {root_mount_id} generate_proof - Generate proof document. params: {feature_id, thinking?, deployed_url?, files_changed?, risk_level?, rollback_time?} get_proof - Get proof for a feature. params: {feature_id} list_proofs - List all proof documents

Federation management for multi-brain coordination. Actions: status - Get comprehensive federation status join - Join a federation via seed peer. params: {seed_peer} leave - Leave the federation gracefully peers - List all federation peers with details sync - Force immediate synchronization with all peers route - Route a task to the optimal brain. params: {task_id, profile?} health - Get federation health dashboard

Governance, Hypervisor & security tools for the Nucleus Agent OS. Actions: auto_fix_loop - Auto-fix loop: Verify->Diagnose->Fix->Verify (3 retries). params: {file_path, verification_command} lock - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] [HYPERVISOR] Lock a file/dir immutable (chflags uchg). params: {path} unlock - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] [HYPERVISOR] Unlock a file/dir. params: {path} set_mode - [HYPERVISOR] Switch IDE context: "red" or "blue". params: {mode} list_directory - [GOVERNANCE] List files in a directory. params: {path} delete_file - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] [GOVERNANCE] Delete a file (governed by Hypervisor). params: {path, confirm?}. HITL: requires confirm=true. watch - [HYPERVISOR] Monitor a file/folder for changes. params: {path} status - [HYPERVISOR] Report current security state of Agent OS curl - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] [EGRESS] Proxied HTTP fetch for air-gapped agents. params: {url, method?} pip_install - [OFF unless NUCLEUS_ENABLE_DESTRUCTIVE_TOOLS=1] [EGRESS] Proxied pip install for air-gapped agents. params: {package} validate_strategic_plan - [PROTOCOL] Validate Strategic mode PLAN has Big Bang [BB##] refs. params: {plan_text, mode?} comply_list - [COMPLIANCE] List available regulatory jurisdictions comply_apply - [COMPLIANCE] Apply jurisdiction config. params: {jurisdiction, brain_path?} comply_report - [COMPLIANCE] Generate compliance status report. params: {brain_path?} audit_report - [COMPLIANCE] Generate audit-ready report. params: {report_format?, since_hours?, brain_path?} kyc_review - [COMPLIANCE] Run KYC demo review. params: {application_id?, brain_path?} sovereign_status - [STATUS] Get sovereignty posture report. params: {brain_path?} trace_list - [DSoR] List decision traces. params: {trace_type?, brain_path?} trace_view - […

Get oriented on the current project state by retrieving relevant context from .brain/. WHEN TO USE: at session start, when you feel lost mid-session, or before starting a new task — this retrieves recent decisions, plan context, and codebase patterns so you don't repeat work or miss prior decisions. The 3-4 search_brain calls run concurrently (asyncio.to_thread + asyncio.gather), so latency is dominated by the slowest section, not the sum. No TB needed. Cross-product filtered (Phase 7 §2) + agent-role filtered (Phase 7 §3) so you only see chunks from this project + this agent role.

Infrastructure: file changes, cloud, marketing & strategy tools. Actions: file_changes - Get pending file change events gcloud_status - Check GCloud auth status gcloud_services - List Cloud Run services. params: {project?, region?} list_services - List Render.com services scan_marketing_log - Scan marketing log for failures synthesize_strategy - Analyze marketing & update strategy. params: {focus_topic?} status_report - Generate State of the Union. params: {focus?} optimize_workflow - Self-optimize workflow cheatsheet manage_strategy - Read/Update strategy doc. params: {action, content?} update_roadmap - Read/Update roadmap. params: {action, item?} growth_pulse - Full growth pipeline: brief→metrics→streak→compound. params: {write_engrams?} capture_metrics - Refresh GitHub+PyPI metrics + gate evaluation. params: {write_engram?}

Report friction/bugs/enhancements to the nucleus team. WHEN TO USE: when the lane misbehaves, a task fails unexpectedly, the SPEC.md format is confusing, or you have an improvement idea. Creates a GitHub issue on the public nucleus-mcp repo (cross-machine visible) AND stores locally. Requires gh CLI auth'd.

Set up an autonomous task-execution loop in a git repo. WHEN TO USE: you have a list of tasks (bugs, features, tests) you want executed automatically without manual prompting — the lane runs watcher/executor/secretary daemons that claim tasks, invoke an LLM to implement them, and independently verify the results. Use this when you want to batch-execute a backlog of well-defined tasks. Creates .brain/, SPEC.md template, and pins via git tag.

Start autonomous lane daemons (watcher + executor + secretary) in background. WHEN TO USE: after nucleus_lane_init and SPEC.md is written — this launches the loop that autonomously claims and executes tasks. The executor invokes an LLM CLI (devin/agy) per task; the secretary independently verifies each result. Runs until nucleus_lane_stop is called.

Check lane status: task counts (PENDING/IN_PROGRESS/DONE/CONFIRMED), daemon health, spec verification. WHEN TO USE: after starting a lane to monitor progress, or before starting to check if a lane is already running.

Stop all running lane daemons. WHEN TO USE: when all tasks are CONFIRMED or you want to pause autonomous execution.

Get the next unread relay message. One call — returns full message body and auto-acks. Long-poll (default 60s; set timeout_seconds). This is the agent's idle loop. Call it, get a message or None, act or re-call. No separate inbox + ack dance. The agent's loop: 1. nucleus_next_message() → blocks up to 60s for a message 2. If message: handle it (execute task, respond to comment, etc.) 3. Re-call nucleus_next_message() — always re-arm, never sit idle 4. Never stop the loop Role is auto-detected from posture (.brain/posture/current.json). No args needed. Returns: dict with: message: full relay message (id, from, subject, body, priority, task_id) or None acked: True if message was auto-acked waited_seconds: how long the poll ran

Satellite view, commitments, loops, patterns & metrics. Actions: satellite - Unified satellite view. params: {detail_level?} scan_commitments - Scan artifacts for new commitments archive_stale - Auto-archive commitments older than 30 days export - Export brain to zip list_commitments - List open commitments. params: {tier?} close_commitment - Close a commitment. params: {commitment_id, method} commitment_health - Get commitment health summary open_loops - View all open loops. params: {type_filter?, tier_filter?} add_loop - Add a new open loop. params: {description, loop_type?, priority?} weekly_challenge - Manage weekly challenge. params: {action?, challenge_id?} patterns - Manage learned patterns. params: {action?} metrics - Get coordination metrics pr_watch - Enumerate stale PRs (>N days), classify (auto-mergeable / billing-stuck / needs-verdict), fire one relay per stale PR to the integration coord. params: {threshold_days?, dry_run?}

Execute a plan file autonomously. WHEN TO USE: you have a plan file (.brain/plans/*.md) you want executed autonomously — parses the plan, creates tasks, starts a mission with budget/time limits. Chains import_plan_as_tasks() then _brain_start_mission_impl() and returns the mission status string.

Import a plan file as PENDING tasks without starting a mission. WHEN TO USE: you have a plan file (.brain/plans/*.md) you want loaded into the task store so the executor daemon / sprint mission can pick the tasks up later — but you don't want to start a mission right now.

List available plan files in .brain/plans with task counts. WHEN TO USE: you want to discover which plan files exist and how many tasks each contains before importing or executing one. Returns: JSON string: a list of dicts each with ``{"name", "path", "size_bytes", "task_count", "format"}``. Missing directory returns ``[]``.

Relay-substrate facade — post / read / ack / status. Actions: post - Send a relay envelope. params: {to, subject, body, sender?, priority?, in_reply_to?, context?, id?, from_session_id?} sender? auto-fills from your session role when omitted. to accepts short role aliases: main, peer, tb, ops, agy, board. "recipient" is accepted as an alias for "to". Returns {sent: bool, id: str (server message_id), error?: str}. inbox - List inbox messages. params: {role?, unread_only?, limit?} role auto-fills from CC_SESSION_ROLE env. Returns {messages: [...], role: str}. ack - Mark messages seen. params: {message_ids: [str], role?} Returns {acked: int, failed: int}. status - Diagnostic (no server call). params: {role?} Returns {is_http_mode, relay_url_set, bearer_set, canonical_role, resolved_inbox_dir}. Bearer resolves per-role at call-time (~/.tb/relay_token_<role>, falling back to NUCLEUS_RELAY_BEARER env) — never passed via this tool's prompt surface. Per ADR-0036 amendment c068abc1 + v0.2.1 Layer A.

Long-poll subscription that pushes ctx.info() on each new inbox file. Replaces bash polling daemons (watch-relay-*.sh) with server-initiated push. Call once at session start (e.g. via SessionStart hook). Server holds the subscription, watches the calling agent's role-specific inbox dir, and fires info-level notifications on each new relay file arrival. Client re-calls this in a loop for persistent coverage. Per PR #1 (CCR-inversion-for-relay-pickup): `inbox_filter` parameter added to BYPASS role-based dir resolution. Use when role detection is unreliable OR when subscribing to a specific canonical inbox (e.g., 'cc_tb'). Closes 3-week-old feedback_relay_arrival_invisible_midsession HARD RULE.

W5 tier routing — route a prompt to the optimal model tier. Actions: route - Route a prompt to cheapest capable model. params: {prompt, complexity?, context?, estimated_output_tokens?} complexity ∈ 'routine' | 'complex' | 'sovereign' (default 'routine') Returns: provider, model, cost estimates, sovereignty tier.

Run engine facade. Actions: create_project {root_uri, trust_mode?} create_conversation {project_id, title} create_run {conversation_id, prompt, runner_id?, model_id?, execution_target?, mode?, idempotency_key?} list_runs {conversation_id?} show_run {run_id} apply_run {run_id} dismiss_run {run_id} cancel_run {run_id, issuer?}

Session management, events, state & checkpoint tools. Actions: save - Save session for later. params: {context, active_task?, pending_decisions?, breadcrumbs?, next_steps?} resume - Resume a saved session. params: {session_id?} list - List all saved sessions check_recent - Check for recent session to resume (alias: "current") end - End work session. params: {summary?, learnings?, mood?} start - Mandatory session start protocol archive_resolved - Archive .resolved.* backup files propose_merges - Detect redundant artifacts, generate merge proposals garbage_collect - Archive stale tasks. params: {max_age_hours?, dry_run?} emit_event - Emit event to brain ledger. params: {event_type, emitter, data, description?} read_events - Read recent events. params: {limit?} get_state - Get brain state. params: {path?} update_state - Update brain state. params: {updates} checkpoint - Save task checkpoint. params: {task_id, step?, progress_percent?, context?, artifacts?, resumable?} resume_checkpoint - Resume from checkpoint. params: {task_id} handoff_summary - Generate handoff summary. params: {task_id, summary, key_decisions?, handoff_notes?} ingest_conversations - Ingest Claude Code JSONL transcripts. params: {mode?: "incremental"|"batch"|"single", session_id?, limit?, dry_run?} search_conversations - Search ingested conversations. params: {query, limit?, session_id?, date_from?, date_to?} list_conversations - List ingested sessions. params: {limit?, offset?, sort?: "recent"|"size"|"turns"} conversation_stats - Aggregate conversation corpus statistics register - [T3.11] Register agent session envelope. params: {session_id, agent, role, provider, worktree_path?, pid?, heartbeat_interval_s?, role_credential?} (role_credential required when NUCLEUS_ROLE_CREDENTIAL=1 — see stone-1.5) heartbeat - [T3.11] Touch last_heartbeat on a…

Orchestration slots, sprints & mission management. Actions: orchestrate - THE GOD COMMAND. params: {slot_id?, model?, alias?, mode?} slot_complete - Mark task complete. params: {slot_id, task_id, outcome?, notes?} slot_exhaust - Mark slot exhausted. params: {slot_id, reset_hours?} status_dashboard - ASCII dashboard. params: {detail_level?} autopilot_sprint - Sprint command. params: {slots?, mode?, halt_on_blocker?, halt_on_tier_mismatch?, max_tasks_per_slot?, budget_limit?, dry_run?} force_assign - Force assign task. params: {slot_id, task_id, acknowledge_risk?} autopilot_sprint_v2 - Enhanced sprint V3.1. params: {slots?, mode?, halt_on_blocker?, halt_on_tier_mismatch?, max_tasks_per_slot?, budget_limit?, time_limit_hours?, dry_run?} start_mission - Start mission. params: {name, goal, task_ids, slot_ids?, budget_limit?, time_limit_hours?, success_criteria?} mission_status - Get mission status. params: {mission_id?} halt_sprint - Halt sprint. params: {reason?} resume_sprint - Resume sprint. params: {sprint_id?}

Sync, artifact, trigger & deploy management for multi-agent coordination. Actions: identify_agent - Register agent identity. params: {role, provider, session_id} (per ADR-0005 §D1) OR legacy {agent_id, environment, role?} (coerced per §D5 until end of Cycle C+2) sync_status - Check current multi-agent sync status sync_now - Manually trigger sync. params: {force?} sync_auto - Enable/disable file watching. params: {enable} sync_resolve - Resolve a file conflict. params: {file_path, strategy?} read_artifact - Read an artifact file. params: {path} write_artifact - Write to an artifact file. params: {path, content} list_artifacts - List artifacts. params: {folder?} trigger_agent - Trigger an agent via event. params: {agent, task_description, context_files?} get_triggers - Get all defined neural triggers evaluate_triggers - Evaluate triggers for an event. params: {event_type, emitter} start_deploy_poll - Start monitoring a Render deploy. params: {service_id, commit_sha?} check_deploy - Check deploy poll status. params: {service_id} complete_deploy - Mark deploy complete. params: {service_id, success, deploy_url?, error?, run_smoke_test?} smoke_test - Run a smoke test. params: {url, endpoint?} shared_read - Read shared state. params: {key} shared_write - Write shared state. params: {key, value, agent_id?} shared_list - List all shared state keys notify - Send notification to all channels. params: {title, message, level?} list_channels - List configured notification channels add_channel - Add a channel. params: {channel_type, webhook_url?} test_channel - Test a channel. params: {channel_name?} relay_post - Post message to another session type (Cowork↔Claude Code). params: {to, subject, body, priority?, context?, sender?, to_session_id?, from_session_id?, in_reply_to?, task_id?} relay_inbox - Read messages fo…

Task management, depth tracking & ADHD context-switch tools. Actions: list - List tasks. params: {status?, priority?, skill?, claimed_by?, required_role?} get_next - Get highest-priority unblocked task. params: {skills, required_role?} claim - Atomically claim a task. params: {task_id, agent_id} update - Update task fields. params: {task_id, updates} add - Create a new task. params: {description, priority?, blocked_by?, required_skills?, source?, task_id?, skip_dep_check?, required_role?, plan_ref?} (alias: "create") import_jsonl - Import tasks from JSONL. params: {jsonl_path, clear_existing?, merge_gtm_metadata?} escalate - Escalate task for human help. params: {task_id, reason} depth_push - Go deeper into subtopic. params: {topic} depth_pop - Come back up one level depth_show - Show current depth state depth_reset - Reset depth to root depth_set_max - Set max safe depth. params: {max_depth} depth_map - Generate exploration map context_switch - Record context switch / ADHD drift check. params: {new_context} context_switch_status - Get context switch metrics context_switch_reset - Reset context switch counter

LLM tiers, telemetry, PEFS notifications & protocol tools. Actions: set_llm_tier - Set default LLM tier. params: {tier} get_llm_status - Get LLM tier configuration record_interaction - Record user interaction timestamp value_ratio - Get Value Ratio metric check_kill_switch - Check Kill Switch status pause_notifications - Pause PEFS notifications resume_notifications - Resume PEFS notifications record_feedback - Record notification feedback. params: {notification_type, score} mark_high_impact - Mark loop closure as high-impact check_protocol - Check protocol compliance. params: {agent_id} request_handoff - Request agent handoff. params: {to_agent, context, request, priority?, artifacts?} get_handoffs - Get pending handoffs. params: {agent_id?} agent_cost_dashboard - Get agent cost tracking dashboard dispatch_metrics - Get dispatch telemetry (per-action timing, error rates) rate_limit_status - Get dispatch rate limiter status (calls per facade, window)

Quick scan for a PENDING task. Returns the task directly if one is available, or None if no task is ready within the timeout. Default timeout is 5s (non-blocking). The agent should NOT loop on this — tasks arrive via relay push. This is a fallback for when the agent wants to check for tasks without waiting for a relay. No args needed — the role is auto-detected from posture (.brain/posture/current.json) or NUCLEUS_AGENT_ROLES env var.