nanoclaw — SLICC's multi-agent architecture

SYNOPSIS

NanoClaw is SLICC's multi-agent system: one cone (main agent) orchestrating multiple scoops (isolated sub-agents). The cone delegates work, scoops execute independently, and results flow back through the orchestrator.

ARCHITECTURE

The system follows a hub-and-spoke model. The cone is the hub — it talks to the human, manages scoops, and synthesizes results. Scoops are the spokes — each runs in a sandboxed environment with its own filesystem, shell, and conversation. Scoops never talk to each other directly; all coordination flows through the cone.

User → Cone (orchestrator) → Scoop A (sandboxed)
                            → Scoop B (sandboxed)
                            → Scoop C (sandboxed)
       ← results ←←←←←←←←←←←←←←←←←←←←←←←←←←←←

CONE

The cone is the main agent ("sliccy"). It has full, unrestricted filesystem access and all tools. Its role is orchestration: understanding user intent, breaking work into tasks, delegating to scoops, and synthesizing results. The cone is the only agent the human interacts with directly.

Cone-exclusive capabilities:

Full read/write access to the entire VFS (no restrictions).
Scoop management tools: scoop_scoop, feed_scoop, drop_scoop, list_scoops.
update_global_memory — update the shared CLAUDE.md visible to all scoops.
Receives completion notifications when scoops finish work.

SCOOPS

Scoops are isolated sub-agents with sandboxed filesystems, their own shells, and independent conversations. They receive complete, self-contained prompts from the cone — they have no access to the cone's conversation history. Each scoop works independently and in parallel with other scoops.

Scoop capabilities:

Core tools: read_file, write_file, edit_file, bash, javascript.
send_message — send progress updates or interim messages.
Own shell instance, own conversation history, own CLAUDE.md memory.

Scoops do NOT have: scoop_scoop, feed_scoop, drop_scoop, list_scoops, or update_global_memory. Only the cone manages scoops.

TOOLS

scoop_scoop(name, [model], [prompt])

Create a new scoop. If prompt is provided, the scoop starts working immediately. Optionally specify a model (e.g., "claude-sonnet-4-6"); defaults to the cone's model. Cone only.
feed_scoop(scoop_name, prompt)

Send a complete, self-contained task to an existing scoop. The prompt must include ALL context — the scoop cannot see the cone's conversation. Fire-and-forget: the cone's tool call returns immediately, and the scoop processes in the background. Cone only.
drop_scoop(scoop_name)

Remove a scoop and destroy its context. Blocked if the scoop has active webhooks or cron tasks. Cone only.
list_scoops

List all registered scoops with folder names and status. Cone only.
send_message(text)

Send a message while still working. Available to both cone and scoops. Used for progress updates or sending multiple messages during a single task.
update_global_memory(content)

Update the global /shared/CLAUDE.md memory file shared across all scoops. Cone only.

MESSAGE ROUTING

When the cone calls feed_scoop, the orchestrator saves the delegation as a channel message and fires the scoop's agent loop asynchronously. The cone's tool call returns immediately — the scoop works in the background.

When a scoop finishes, its response is buffered by the orchestrator and routed back to the cone's message queue. The cone is notified and can read the scoop's output to synthesize results.

Cone → feed_scoop("research", prompt) → returns immediately
  Orchestrator → queues prompt → Scoop processes in background
  Scoop completes → Orchestrator buffers response → Cone's message queue

FILESYSTEM ISOLATION

Each scoop gets a sandboxed filesystem enforced by RestrictedFS:

/scoops/{folder}/ — read/write. The scoop's private workspace, home, and tmp.
/shared/ — read/write. The collaboration point between cone and all scoops.
/workspace/ — read-only. Access to cone's workspace including skills.

Write operations outside allowed paths throw EACCES. Read operations outside allowed paths return "not found". The cone has unrestricted access to the entire VFS.

SHARED DIRECTORY

/shared/ is the primary collaboration point. Both cone and all scoops can read and write here. Common patterns:

Scoops write results to /shared/results.md for the cone to synthesize.
Sprinkles live in /shared/sprinkles/{name}/.
Global memory at /shared/CLAUDE.md is readable by all agents.

SPRINKLE OWNERSHIP AND LICK ROUTING

Sprinkles (persistent UI panels) are created by scoops. When a user interacts with a sprinkle, it generates a lick event. The lick routes through the cone back to the owning scoop. This is why scoops that own sprinkles must stay alive — dropping them breaks lick routing.

Lick messages bypass the normal trigger check (they are explicitly routed to their target scoop).

HOW IT DIFFERS

NanoClaw differs from traditional multi-agent frameworks:

Browser-native — runs entirely in the browser. No external orchestration server.
VFS-based isolation — sandboxing via RestrictedFS path ACLs on a shared VFS, not separate containers or processes.
Shell-first — scoops use bash, not bespoke tool APIs. New capabilities are shell commands, not dedicated integrations.
No MCP overhead — tools are direct function calls within the browser context, not remote procedure calls over a protocol.
Fire-and-forget delegation — the cone doesn't block waiting for scoops. It continues working and gets notified on completion.

ORCHESTRATOR

The Orchestrator class manages the entire NanoClaw lifecycle: registering and unregistering scoops, creating scoop contexts (filesystem + shell + agent), routing messages between cone and scoops, buffering scoop responses, and managing VFS setup. It ensures scoops are initialized before messages are delivered and handles error recovery for failed scoop tabs.