create-ironclaws 1.0.0

package/template/docs/how-it-works.md

@@ -0,0 +1,496 @@
+# NanoClaw — How It Works
+
+A technical guide to the system you've built: concepts, design decisions, and where to find them in the code.
+
+---
+
+## Table of Contents
+
+1. [Big Picture](#1-big-picture)
+2. [Message Flow — From Slack to Agent and Back](#2-message-flow)
+3. [Secrets Management](#3-secrets-management)
+4. [OneCLI Proxy](#4-onecli-proxy)
+5. [Network Enforcement — iptables](#5-network-enforcement)
+6. [Container Isolation](#6-container-isolation)
+7. [Tools and Skills](#7-tools-and-skills)
+8. [IPC — How Agents Talk Back](#8-ipc)
+9. [Task Scheduling](#9-task-scheduling)
+10. [Agent Registration](#10-agent-registration)
+11. [Mount Security](#11-mount-security)
+12. [The Group Queue](#12-the-group-queue)
+13. [Remaining Known Issues](#13-remaining-known-issues)
+
+---
+
+## 1. Big Picture
+
+NanoClaw is a single Node.js host process that manages a fleet of AI agents. Each agent is a Docker container running Claude Code. The host handles Slack, routing, scheduling, and security. Agents do the actual work.
+
+```
+Slack
+  │
+  ▼
+NanoClaw host (src/index.ts)
+  │  reads .env, agents.yaml, mount-allowlist.json
+  │
+  ├── Message router ──► spawns Docker container per agent
+  ├── Task scheduler ──► spawns containers on schedule
+  └── IPC watcher    ──► reads results from containers
+          │
+          ▼
+    Docker container (argus-claude:latest)
+      ├── Claude Code (the AI)
+      ├── agent-runner (Node.js wrapper — container/agent-runner/)
+      ├── Python tools (container/tools/)
+      └── Skills (SKILL.md files)
+```
+
+Key design principle: **the host is the trust boundary**. The host holds all secrets, enforces all network rules, and validates all mount requests. Containers are untrusted workers — they can only reach the internet through the OneCLI proxy, and only with the credentials they've been explicitly given.
+
+**Where to read:**
+- `src/index.ts` — the main loop, message routing, session management
+- `src/container-runner.ts` — how containers are spawned
+- `container/Dockerfile.argus` — what's baked into the image
+- `CLAUDE.md` — high-level architecture reference
+
+---
+
+## 2. Message Flow
+
+### From Slack to Agent
+
+```
+1. Slack sends event (Socket Mode WebSocket)
+        │
+2. NanoClaw receives it → stores in DB (messages table)
+        │
+3. Router checks: does this message contain a trigger word?
+   (@Argus, @Byte, etc.)
+        │
+   Yes ─┤
+        ├── Fetch all accumulated messages since last run for this agent
+        ├── Build prompt (messages + channel members + agent identity)
+        └── Enqueue in GroupQueue
+                │
+4. GroupQueue checks concurrency limits → spawns Docker container
+        │
+5. Container starts:
+   - Claude Code reads the prompt
+   - Runs tools (Bash, Python scripts, MCP tools)
+   - Produces output
+        │
+6. agent-runner captures output → writes to IPC file
+        │
+7. IPC watcher (host-side) reads the file → sends Slack message
+```
+
+**No trigger?** The message is stored in the DB. Next time a trigger arrives, NanoClaw pulls ALL accumulated messages as context — so the agent sees the full conversation.
+
+**Where to read:**
+- `src/index.ts:280–440` — message routing logic
+- `src/db.ts` — `getNewMessages()`, `getMessagesSince()`, `storeMessage()`
+- `src/group-queue.ts` — the concurrency manager
+- `container/agent-runner/src/index.ts` — what runs inside the container
+
+### From Agent Back to Slack
+
+Agents have two ways to send messages:
+
+1. **Final response** — whatever Claude outputs at the end of the run gets posted to the channel
+2. **`send_message` MCP tool** — sends a message mid-run without waiting for completion (progress updates)
+
+Both go through IPC files. The host's IPC watcher picks them up and posts to Slack.
+
+**Where to read:**
+- `src/ipc.ts` — the watcher
+- `container/agent-runner/src/ipc-mcp-stdio.ts` — MCP tools agents can call
+
+---
+
+## 3. Secrets Management
+
+This is the most important system to understand. The design goal: **no long-lived secrets ever enter a container**.
+
+### The Four Credential Categories
+
+#### A. Service API Keys (Elastic, Jira, Confluence, Slack, Intercom, Ardoq)
+These never enter containers at all. The OneCLI proxy intercepts HTTPS requests and injects the `Authorization` header server-side. The container makes a request to `jira.atlassian.com`, OneCLI intercepts, adds `Authorization: Basic <token>`, forwards it. The container only ever sees the base URL.
+
+```
+Container → HTTPS_PROXY → OneCLI → adds Authorization header → Jira
+```
+
+#### B. GitHub Tokens
+The GitHub App private key (`github-app.pem`) never enters containers. Before spawning, the host generates a short-lived (~1 hour) installation token using the App credentials. Only the token is injected as `GITHUB_TOKEN`.
+
+```python
+# Concept:
+pem + app_id + installation_id → GitHub API → short-lived token
+# Only the token goes into the container env
+```
+
+**Where to read:** `src/github-token.ts`, `container-runner.ts:448–465`
+
+#### C. Google Access Tokens
+Same pattern as GitHub. The host holds the OAuth refresh token. Before spawning, it calls Google's token endpoint to get a short-lived access token, injects only that.
+
+**Where to read:** `src/google-token.ts`, `container-runner.ts:470–478`
+
+#### D. Expensify Credentials (the exception)
+Expensify embeds credentials in the **JSON request body** (not in HTTP headers). OneCLI can only inject headers, so it can't handle Expensify. These two env vars (`EXPENSIFY_PARTNER_USER_ID`, `EXPENSIFY_PARTNER_USER_SECRET`) must be passed directly to the container. This is explicitly documented as a known trade-off, and only the `expense-policy-checker` agent gets them.
+
+**Where to read:** `agent-credentials.yaml` (comment on expense-policy-checker block)
+
+### Per-Agent Selective Credentials
+
+Each agent only gets the credentials it actually needs. This is configured in two places:
+
+**`agent-credentials.yaml`** — controls which env vars from the host's `.env` are forwarded:
+```yaml
+agents:
+  argus-alert:
+    config:
+      - GITHUB_TOKEN        # gets a fresh token injected
+      - ELASTIC_BASE_URL    # just a URL, not a secret
+```
+
+**`agents.yaml`** — controls which OneCLI credential sets are linked (for service auth via proxy):
+```yaml
+- folder: byte-it-internal
+  onecli_secrets: [slack, litellm]   # can call Slack API + Claude API
+```
+
+**Where to read:** `agent-credentials.yaml`, `agents.yaml`, `src/container-runner.ts:50–130` (the credential loading functions)
+
+---
+
+## 4. OneCLI Proxy
+
+OneCLI is an HTTPS man-in-the-middle proxy that runs as a Docker container alongside NanoClaw. Every agent container has its outbound HTTPS traffic routed through it.
+
+### How It Works
+
+When `applyContainerConfig()` is called before spawning a container, OneCLI's SDK injects these env vars:
+```
+HTTPS_PROXY=http://x:<access-token>@host.docker.internal:10255
+HTTP_PROXY=http://x:<access-token>@host.docker.internal:10255
+https_proxy=...  (lowercase versions for Python/other tools)
+NODE_USE_ENV_PROXY=1
+SSL_CERT_FILE=/tmp/onecli-combined-ca.pem  (OneCLI's MITM CA cert)
+```
+
+Every HTTPS call from the container (Python's `urllib.request`, `requests`, Node.js `fetch`, `curl`, `git`) goes through the proxy automatically because of these env vars.
+
+When OneCLI intercepts a request:
+1. Looks up the access token → identifies which agent this is
+2. Checks if this agent has a credential linked for the target hostname
+3. If yes: injects the `Authorization: Bearer <secret>` header
+4. If no credential: proxies the request unchanged (or blocks if configured to do so)
+
+The `access_token` in the proxy URL is the per-agent token stored in OneCLI's PostgreSQL database. It's regenerated each time `setup-agents.sh` is run.
+
+### Git Authentication Fix
+
+Git has a bug with MITM proxies: it doesn't retry after a 401. To work around this, NanoClaw pre-injects the auth header for git before the first request:
+```
+GIT_CONFIG_KEY_0=http.extraHeader
+GIT_CONFIG_VALUE_0=Authorization: Basic <base64(x:token)>
+```
+
+**Where to read:**
+- `src/container-runner.ts:482–499` — where `applyContainerConfig()` is called
+- `node_modules/@onecli-sh/sdk/lib/index.js` — what it actually injects
+- `agents.yaml` — `onecli_id` and `onecli_secrets` per agent
+- `setup-agents.sh:101–124` — how agents are registered in OneCLI's DB
+
+---
+
+## 5. Network Enforcement
+
+### The Problem
+Without network enforcement, a compromised or misbehaving agent could call external APIs, exfiltrate data, or perform actions you haven't authorized.
+
+### The Solution: iptables
+
+After each container spawns, NanoClaw adds rules to the `DOCKER-USER` iptables chain (Docker's hook for custom rules). The rules are:
+
+```
+ACCEPT  from <container_ip> to <onecli_ip>  port 10255  # OneCLI proxy — allowed
+ACCEPT  from <container_ip>                 port 53     # DNS — allowed  
+REJECT  from <container_ip>                 all traffic # everything else — immediate rejection
+```
+
+The `REJECT` (not `DROP`) matters: with `DROP`, a blocked connection hangs for minutes waiting for a TCP timeout. With `REJECT --reject-with icmp-port-unreachable`, the connection fails immediately, so Claude doesn't wait.
+
+### Why All Traffic Goes Through OneCLI
+
+The iptables rules only allow port 10255 (OneCLI proxy). Since `HTTPS_PROXY` is set in the container, ALL HTTPS calls go through port 10255 automatically. So:
+- Direct `api.anthropic.com:443` connections → REJECTED (but these go through proxy anyway)
+- Claude API calls → port 10255 → OneCLI → forwarded with credentials → OK
+- Expensify calls → port 10255 → OneCLI → forwarded without modification (body unchanged) → OK
+- Any unauthorized service → port 10255 → OneCLI → no credential → 401 or blocked
+
+### Cleanup
+
+Rules are tagged with the container name (`--comment "nanoclaw-argus-deps-123"`). When the container exits, all its rules are deleted. On NanoClaw startup, stale rules from any previous run are cleaned up automatically.
+
+**Where to read:**
+- `src/network-policy.ts` — `applyContainerIptables()`, `cleanupContainerIptables()`
+- `src/container-runtime.ts:102–121` — `cleanupStaleIptablesRules()` (startup cleanup)
+- `src/container-runner.ts:591–602` — where iptables is called after spawn
+
+---
+
+## 6. Container Isolation
+
+Each container gets its own isolated environment:
+
+### Session Directory
+Each agent has a persistent home directory at `data/sessions/{agentFolder}/`. This is mounted as `/home/node` inside the container. Claude Code stores its conversation history (JSONL files), MEMORY.md, and settings here. Session files from one agent are completely invisible to another.
+
+### IPC Namespaces
+Each group has its own IPC directory at `data/ipc/{agentFolder}/`. Agents can only write to their own namespace. The host enforces this at the IPC file processing level.
+
+### Skills and Tools
+Each container only gets the skills and tools listed in `agent-credentials.yaml`. See [Section 7](#7-tools-and-skills).
+
+### Worktrees
+When an agent needs to modify code (e.g. argus-deps raising a PR), it doesn't work on your live checkout. NanoClaw creates a git worktree — a separate clone of the repo — at `data/worktrees/{agentFolder}/repo/`. This is mounted read-write into the container while the actual repo stays untouched.
+
+**Where to read:**
+- `src/worktree.ts` — worktree creation/management
+- `src/container-runner.ts:160–380` — the full mount list construction
+- `data/sessions/` — look here to see active agent session files
+
+---
+
+## 7. Tools and Skills
+
+### The Difference
+- **Skills** (`container/skills/`) — markdown files (`SKILL.md`) that Claude reads for instructions. They tell Claude how to do things (e.g. how to format Slack messages, how to browse the web).
+- **Tools** (`container/tools/`) — Python scripts that Claude can execute with the `Bash` tool. They provide actual functionality (e.g. query Elasticsearch, post to Jira).
+
+### How the Allowlist Works
+
+`agent-credentials.yaml` defines a two-layer allowlist:
+```yaml
+common:
+  skills: [capabilities, status, slack-formatting]  # every agent gets these
+  tools: []                                          # no tools by default
+
+agents:
+  argus-alert:
+    skills: []                        # adds nothing extra
+    tools: [elastic_query.py, jira_tool.py]  # but gets these tools
+  global-claw:
+    skills: [agent-browser, agent-status, edit-agent]  # dangerous skills
+    tools: [elastic_query.py, jira_tool.py, ...]       # all tools
+```
+
+**Dangerous skills** (`edit-agent`, `agent-browser`, `agent-status`) are NOT in the common layer. Only `global-claw` has them by explicit opt-in.
+
+### How It's Enforced
+
+Before spawning a container, the host:
+1. Computes the allowed skill set (common + agent-specific)
+2. Copies only those skill directories to `data/sessions/{agent}/.claude/skills/`
+3. Computes the allowed tool set
+4. Copies only those tool files to `data/tools/{agent}/`
+5. Mounts `data/tools/{agent}` → `/workspace/extra/tools` (read-only)
+
+Skills and tools NOT in the allowlist are never present in the container.
+
+**Where to read:**
+- `src/container-runner.ts:50–160` — `getAgentEnvKeys()`, `getAgentSkills()`, `getAgentTools()`
+- `agent-credentials.yaml` — the full allowlist configuration
+
+---
+
+## 8. IPC
+
+IPC (Inter-Process Communication) is how agents running inside containers send things back to the host without waiting for their run to finish.
+
+### The Mechanism
+
+The host mounts a directory into the container at `/workspace/ipc/{agentFolder}/`. The container writes JSON files into subdirectories:
+- `messages/` — send a Slack message now (mid-run)
+- `tasks/` — create/update/pause/cancel a scheduled task
+- `input/` — the host writes here to send follow-up messages to an active container
+
+The host runs a polling loop (every 1 second) watching these directories. When it sees a new file, it processes it and deletes it.
+
+### The MCP Bridge
+
+Inside the container, agents don't write files directly. They call MCP tools:
+```
+Claude Code → mcp__nanoclaw__send_message → ipc-mcp-stdio.js → writes JSON file → /workspace/ipc/...
+```
+
+The `ipc-mcp-stdio.js` process is a local MCP server. Claude Code connects to it via stdio. When Claude calls `send_message`, `schedule_task`, etc., the MCP server writes the corresponding IPC file atomically (write to `.tmp`, then rename — so the host never reads a partial file).
+
+### Available MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `send_message` | Send a Slack message immediately while still running |
+| `schedule_task` | Create a recurring or one-time scheduled task |
+| `update_task` | Modify an existing task's schedule or prompt |
+| `pause_task` / `resume_task` / `cancel_task` | Manage task lifecycle |
+| `list_tasks` | See scheduled tasks for this group |
+| `register_group` | Register a new agent channel (main group only) |
+
+**Where to read:**
+- `src/ipc.ts` — the host-side watcher
+- `container/agent-runner/src/ipc-mcp-stdio.ts` — the MCP server inside containers
+- `container/agent-runner/src/index.ts:410–435` — how agent-runner connects to the MCP server
+
+---
+
+## 9. Task Scheduling
+
+Agents can schedule themselves (or be pre-configured) to run on a schedule — no human message needed.
+
+### Schedule Types
+
+```
+cron:     "0 11 * * 1-5"   → runs at 11:00 AM on weekdays (uses TIMEZONE from config)
+interval: 3600000           → runs every 60 minutes (milliseconds, drift-free)
+once:     ISO timestamp     → runs once at that time, then marked complete
+```
+
+### How It Works
+
+Every 60 seconds, the scheduler queries:
+```sql
+SELECT * FROM scheduled_tasks
+WHERE status = 'active' AND next_run IS NOT NULL AND next_run <= now
+```
+
+For each due task, it enqueues a container run. Crucially, `next_run` is advanced **before** the container starts — so if the run takes 10 minutes, the scheduler won't see it as due again during that time.
+
+### Silent Tasks
+
+Tasks can have `silent=1` in the database. Silent tasks run, but their results are NOT posted to Slack. Used for background maintenance — the byte daily transcript sync is silent so it doesn't clutter the standup channel.
+
+### Context Mode
+
+Tasks have a `context_mode`:
+- `"group"` — uses the agent's current conversation session; the agent has memory of what was discussed
+- `"isolated"` — fresh session each time; task prompt must be self-contained
+
+### Pre-Run Scripts
+
+A task can have a `script` field (bash script). The script runs first. Its last line must be JSON:
+```json
+{"wakeAgent": true, "data": {"key": "value"}}
+```
+If `wakeAgent: false`, the task ends without calling Claude — useful for tasks that only need to run under certain conditions (e.g. "only wake the agent if there are new alerts").
+
+**Where to read:**
+- `src/task-scheduler.ts` — `startSchedulerLoop()`, `runTask()`, `computeNextRun()`
+- `src/db.ts:515–541` — `getDueTasks()`, `updateTaskAfterRun()`
+
+---
+
+## 10. Agent Registration
+
+### Automatic Registration on Startup
+NanoClaw reads `agents.yaml` on every startup and auto-registers any agent whose channel ID env var is set in `.env` but isn't in the DB yet. This means a fresh install only requires filling in `.env` and starting NanoClaw — no manual script needed.
+
+The `autoRegisterAgentsFromYaml()` function in `src/index.ts` handles this. It also runs `scripts/setup-onecli-secrets.sh` automatically when credentials change (detected via hash of relevant env vars).
+
+### Dynamic Registration (Main Group)
+The `global-claw` agent (the meta-agent) can register new agents at runtime using the `register_group` MCP tool. Only the main group can do this — NanoClaw enforces this at the IPC processing level.
+
+### What Registration Does
+
+1. Inserts row in `registered_groups` table (NanoClaw's SQLite)
+2. Creates MEMORY.md in the group's folder
+3. Calls `onecli.ensureAgent()` to create the agent in OneCLI's PostgreSQL (best-effort)
+
+**Where to read:**
+- `agents.yaml` — agent definitions (single source of truth)
+- `src/index.ts` — `autoRegisterAgentsFromYaml()`, `ensureOneCLISecrets()`
+- `src/ipc.ts:280–340` — `register_group` IPC processing
+- `src/db.ts:700–760` — `upsertRegisteredGroup()`
+
+---
+
+## 11. Mount Security
+
+The host can mount directories into containers (e.g. repos, config files). Without guardrails, an agent could request a mount of `~/.ssh` and exfiltrate keys.
+
+### The Allowlist
+
+Stored at `~/.config/nanoclaw/mount-allowlist.json` — **outside the project directory**. Containers can't read this file. Only the host process reads it.
+
+```json
+{
+  "allowedRoots": [
+    { "path": "~/repos/my-repo", "allowReadWrite": false }
+  ],
+  "blockedPatterns": [".ssh", ".aws", ".gnupg", "id_rsa", "credentials", "..."],
+  "nonMainReadOnly": true
+}
+```
+
+Blocked patterns are checked against both the requested path and all parent directories. If a path matches any blocked pattern, the mount is rejected even if the root is allowed.
+
+`nonMainReadOnly: true` forces all mounts for non-main agents to read-only regardless of what was requested.
+
+**Where to read:**
+- `src/mount-security.ts` — `validateAdditionalMounts()`
+- `~/.config/nanoclaw/mount-allowlist.json` — your actual allowlist
+
+---
+
+## 12. The Group Queue
+
+NanoClaw runs multiple agents concurrently but has limits. The `GroupQueue` (`src/group-queue.ts`) manages this.
+
+### Concurrency Model
+
+- Global limit: `MAX_CONCURRENT_CONTAINERS` (configurable in `.env`)
+- Per-group: one container at a time (new messages wait while one is running)
+- Task priority: pending tasks are run before pending messages
+
+### Key Behaviors
+
+**Message queuing**: If a message arrives while the agent is already running, it's queued. When the current run finishes, the next run picks up queued messages.
+
+**Retry with backoff**: If a container exits with an error, NanoClaw retries with exponential backoff (5s → 10s → 20s → 40s → 80s). After 5 retries, the message is dropped. On "No conversation found" errors, the session is cleared before retry.
+
+**Idle close**: When an agent finishes its response, its container stays open for `IDLE_TIMEOUT` (30 minutes by default) — waiting for follow-up messages. If none arrive, the container gets a close sentinel and exits.
+
+**Where to read:**
+- `src/group-queue.ts` — the full implementation
+- `src/config.ts` — `MAX_CONCURRENT_CONTAINERS`, `IDLE_TIMEOUT`
+
+---
+
+## 13. Remaining Known Issues
+
+Three items remain open from the original audit. Everything else has been addressed.
+
+| Issue | Location | Fix |
+|-------|----------|-----|
+| **Mount allowlist not reloadable** — changes to `mount-allowlist.json` require NanoClaw restart | `src/mount-security.ts` | Watch the file with `fs.watch`, or document restart requirement clearly |
+| **No rate limit on IPC writes** — a container could write thousands of IPC files before the host drains them | `src/ipc.ts` | Add a file count limit per group namespace |
+| **No per-group concurrency limit** — one runaway agent could hold all container slots and starve others | `src/group-queue.ts` | Track active count per group; cap at configurable limit |
+
+---
+
+## What to Read Next
+
+If you want to go deeper on a specific area:
+
+| Topic | Start here |
+|-------|-----------|
+| How a message becomes a container | `src/index.ts:280–430` |
+| How containers are built | `src/container-runner.ts` (top to bottom) |
+| Secrets and credentials | `agent-credentials.yaml` + `src/container-runner.ts:50–130` |
+| Network security | `src/network-policy.ts` |
+| How agents talk back | `src/ipc.ts` + `container/agent-runner/src/ipc-mcp-stdio.ts` |
+| Scheduling | `src/task-scheduler.ts` |
+| What OneCLI does | `setup-agents.sh` + `node_modules/@onecli-sh/sdk/lib/index.js` |
+| Security model end-to-end | This doc → `src/mount-security.ts` → `src/network-policy.ts` |

package/template/eslint.config.js

@@ -0,0 +1,32 @@
+import globals from 'globals'
+import pluginJs from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import noCatchAll from 'eslint-plugin-no-catch-all'
+
+export default [
+  { ignores: ['node_modules/', 'dist/', 'container/', 'groups/'] },
+  { files: ['src/**/*.{js,ts}'] },
+  { languageOptions: { globals: globals.node } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    plugins: { 'no-catch-all': noCatchAll },
+    rules: {
+      'preserve-caught-error': ['error', { requireCatchParameter: true }],
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          args: 'all',
+          argsIgnorePattern: '^_',
+          caughtErrors: 'all',
+          caughtErrorsIgnorePattern: '^_',
+          destructuredArrayIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          ignoreRestSiblings: true,
+        },
+      ],
+      'no-catch-all/no-catch-all': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+]

package/template/groups/forge/CLAUDE.md

@@ -0,0 +1,107 @@
+# Forge — IronClaws Guide Agent
+
+You are Forge, the built-in guide for IronClaws. You help people understand how the platform works, build new agents, troubleshoot problems, and get the most out of their setup.
+
+You are running inside IronClaws itself — which means you can inspect the codebase, read configuration files, and help make changes directly.
+
+---
+
+## What you know
+
+### How IronClaws works
+
+IronClaws is a Node.js host process that manages a fleet of AI agents. Each agent runs in its own Docker container with isolated credentials, filesystem, and memory. The host handles Slack, routing, scheduling, and security.
+
+Key files:
+- `agents.yaml` — defines the agent fleet (folder, name, channel, secrets)
+- `agent-credentials.yaml` — controls what each agent can access (env vars, tools, skills)
+- `.env` — all credentials and channel IDs (never committed to git)
+- `groups/{agent-name}/CLAUDE.md` — the agent's identity and instructions
+- `docker-compose.yml` — starts OneCLI (the credential proxy) and Postgres
+- `src/` — the host process TypeScript source
+
+### How to add a new agent
+
+**The short version:**
+1. Create `groups/my-agent/CLAUDE.md` — write the agent's identity and instructions
+2. Add an entry to `agents.yaml`
+3. Add the channel ID to `.env`
+4. Restart IronClaws — the agent auto-registers
+
+**`agents.yaml` entry:**
+```yaml
+  - folder: my-agent
+    name: "My Agent"
+    trigger: "@Argus"
+    channel_env: MY_AGENT_CHANNEL_ID
+    requires_trigger: false
+    onecli_secrets: [litellm]
+    onecli_id: <python3 -c "import uuid; print(uuid.uuid4())">
+```
+
+**`.env` entry:**
+```
+MY_AGENT_CHANNEL_ID=C...
+```
+
+**`groups/my-agent/CLAUDE.md` starter:**
+```markdown
+# Agent Name
+
+One sentence: what this agent does.
+
+## What you do
+Clear description of responsibilities.
+
+## How to respond
+Tone, format, constraints.
+```
+
+**`agent-credentials.yaml`** (only needed if the agent uses specific tools or env vars):
+```yaml
+  my-agent:
+    skills: []
+    tools: [jira_tool.py]   # tools from container/tools/
+    config:
+      - SOME_API_URL
+```
+
+### How credentials work
+
+Agents never see raw API keys. OneCLI (the HTTPS proxy) intercepts outbound requests and injects Authorization headers. `onecli_secrets` in `agents.yaml` controls which credentials flow to which agent. Run `bash scripts/setup-onecli-secrets.sh` to register new credentials — this runs automatically on startup when credentials change.
+
+### Available tools
+
+| Tool | What it does |
+|------|-------------|
+| `jira_tool.py` | Jira CRUD — get, search, create, update, comment |
+| `elastic_query.py` | Query Kibana/Elasticsearch |
+| `slack_history_tool.py` | Read Slack channel history |
+| `gdrive_tool.py` | Read Google Drive files |
+
+Add tools to an agent via `agent-credentials.yaml` → `tools:`.
+
+---
+
+## How to help
+
+**Building a new agent** — draft the CLAUDE.md, show the agents.yaml + .env entries, explain what OneCLI secrets they need if any.
+
+**Explaining how things work** — you have full access to the codebase via `Read` and `Bash`. Read the source and explain in plain language.
+
+**Troubleshooting:**
+- Agent not responding → check `~/.config/nanoclaw/sender-allowlist.json` has the channel (auto-added on restart if channel is in `.env`)
+- Container not starting → Docker Desktop running? Image built? (`cd container && ./build.sh && ./build-argus.sh`)
+- Credentials failing → run `bash scripts/setup-onecli-secrets.sh`
+- Slow startup → large JSONL files in `data/sessions/`; delete to reset
+
+---
+
+## Memory
+
+Append to `MEMORY.md` when you build something or find something notable:
+```
+## YYYY-MM-DD
+- Built: [agent name] — [what it does]
+- Fixed: [issue]
+```