setup

name	setup
description	Bootstrap an UnClaw agent from scratch. Converts a stock Claude Code instance into a persistent personal agent with identity, memory, and scheduling.

Agent Setup

This skill bootstraps the entire agent. Do not assume hooks, launchd jobs, or even .claude/settings.json already exist.

Step 0: Install or repair the core scaffold

Before personalizing anything:

1. Ensure these directories exist:

   • .claude/
   • .claude/rules/
   • .claude/skills/
   • .claude/scripts/
   • .claude/runtime/launchd/
   • memory/
   • daily-logs/

2. Ensure these critical files exist:

   • CLAUDE.md
   • identity/SOUL.md
   • identity/user.md
   • identity/memory.md
   • config/agent.env
   • .claude/settings.json
   • .claude/rules/*.md
   • .claude/scripts/*.sh
   • templates/settings.json
   • templates/launchd/*.plist

3. If .claude/settings.json is missing or malformed, recreate it from templates/settings.json.

4. Verify these required hooks exist in .claude/settings.json:

   • SessionStart
   • Notification
   • PreCompact
   • PostCompact
   • PostToolUse

   If any are missing, repair .claude/settings.json from templates/settings.json.

5. Ensure scripts are executable:

   chmod +x bin/start-agent.sh bin/setup.sh .claude/scripts/*.sh
   

Step 1: Gather identity and role

Ask the user for:

• Agent name (e.g. "Ray", "Jarvis", "Friday")
• Owner name and full name
• Agent role — what this agent is. Not just "engineer." Could be: software engineer, research assistant, content creator, financial analyst, habit coach, food/nutrition tracker, writing partner, ops/devops specialist, data analyst, product manager, or anything else. Let the user type a custom role. This determines the agent's identity, expertise framing, and domain-specific rules.
• Domain expertise — the equivalent of "tech stack" but for any role. Examples:
  • Software engineer → "TypeScript, React, Node.js"
  • Financial analyst → "equity research, DCF modeling, Bloomberg"
  • Content creator → "SEO, WordPress, video editing, social media"
  • Habit coach → "behavioral psychology, habit tracking, accountability"
  • Research assistant → "academic papers, literature review, citation management"
• Timezone
• OS
• Editor
• Communication style

Step 2: Personalize files

Replace placeholders in:

• CLAUDE.md — {{AGENT_NAME}}, {{OWNER_NAME}}, {{AGENT_ROLE}}
• identity/SOUL.md — {{AGENT_NAME}}, {{OWNER_NAME}}, {{AGENT_ROLE}}
• identity/user.md — {{OWNER_NAME}}, {{OWNER_FULL_NAME}}, {{TIMEZONE}}, {{DOMAIN_EXPERTISE}}, {{OS}}, {{EDITOR}}, {{COMMUNICATION_STYLE}}
• config/agent.env — AGENT_SESSION_NAME (lowercase agent name), AGENT_CHANNEL
• .claude/rules/communication.md — {{OWNER_NAME}}
• .claude/skills/daily-standup/SKILL.md — {{OWNER_NAME}}
• .claude/skills/distill-session/SKILL.md — {{OWNER_NAME}}
• .claude/skills/search-memory/SKILL.md — {{OWNER_NAME}}

Generate .claude/rules/domain.md

Generate this file based on the chosen role and domain expertise. It should contain role-appropriate conventions and best practices. Examples:

• Software engineer → coding conventions, testing practices, linting rules
• Content creator → tone guides, SEO checklist, publishing workflow
• Financial analyst → data sourcing rules, model conventions, disclosure practices
• Research assistant → citation style, source evaluation criteria, note-taking format
• Habit coach → tracking format, check-in cadence, encouragement style
• Any role → the file should feel like a senior practitioner wrote their working standards

Keep it concise (under 20 lines). The user can always expand it later.

Use config/agent.env as the source of truth for runtime config:

• AGENT_SESSION_NAME → lowercase agent name
• AGENT_CHANNEL → blank by default, filled if messaging is configured
• TELEGRAM_STATE_DIR → per-agent path, set only if Telegram is configured

Step 3: Messaging channel (optional)

Ask: "Do you want to connect a messaging channel like Telegram?"

If yes, walk through the prerequisites first, then configure the channel.

Prerequisites

Handle these before configuring the channel. Do each silently and report the result to the user.

1. Claude Code channels

Check ~/.claude/settings.json for "DISABLE_TELEMETRY": "1" in the env object.

• If present, remove it. Claude Code uses feature flags for channels, and this setting causes --channels to fall back to "Channels are not currently available."
• Also check shell profiles for DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. If either is exported there, remove it and restart the terminal.

2. Bun

The Telegram MCP server runs on Bun. Run bun --version to check.

• If installed, tell the user which version is present and move on.
• If not found, install it with curl -fsSL https://bun.sh/install | bash, then verify with bun --version. Tell the user it was installed.

3. Telegram bot token

The user needs to create a bot through BotFather — this is the one step that requires manual action on their phone/desktop. Tell the user:

Open @BotFather on Telegram and send /newbot. It asks for a name (display name, anything) and a username (must end in bot, e.g. my_assistant_bot). BotFather replies with a token like 123456789:AAHfiqksKZ8... — copy the whole thing including the number and colon, and paste it here.

Wait for the user to provide the token before proceeding.

4. Telegram plugin

Check if the Telegram plugin is already installed by running claude plugin list 2>&1 | grep -i telegram or checking ~/.claude/plugins/installed_plugins.json.

• If already installed and enabled, tell the user it's present and move on.
• If not installed, tell the user to run these in a Claude Code session:

  /plugin install telegram@claude-plugins-official
  /reload-plugins
  

  If running inside Cursor rather than the Claude Code CLI, add the Telegram MCP server entry to .cursor/mcp.json instead (see the plugin's README for the server command and args).

After either path, verify the Telegram plugin appears in the installed list. Tell the user the result. Also verify if the Telegram MCP server appears in the active MCP list.

Per-agent Telegram isolation

Each agent gets its own Telegram state directory so multiple agents can run different bots on the same machine without conflict. The Telegram MCP plugin reads TELEGRAM_STATE_DIR from its environment; config/agent.env vars are auto-exported via set -a in the session scripts, so child processes (including MCP servers) inherit them.

1. Create the per-agent state directory: ~/.claude/channels/telegram-<agent-name>/ (e.g. telegram-tony, telegram-ray — lowercase agent name)
2. Create ~/.claude/channels/telegram-<agent-name>/.env with TELEGRAM_BOT_TOKEN=<token>
3. Create ~/.claude/channels/telegram-<agent-name>/access.json with:

   {"dmPolicy": "pairing", "allowFrom": [], "groups": {}, "pending": {}}
   

4. Write these lines into config/agent.env:

   AGENT_CHANNEL="plugin:telegram@claude-plugins-official"
   TELEGRAM_STATE_DIR="$HOME/.claude/channels/telegram-<agent-name>"
   

Why per-agent dirs? The Telegram MCP plugin defaults to ~/.claude/channels/telegram/ for its bot token and access list. If two agents share that path, they fight over the same bot token (409 Conflict) and share access lists. TELEGRAM_STATE_DIR overrides this per-agent.

Auto-pair the owner's Telegram account

After the agent is started and Telegram is connected:

1. Tell the user: "DM your bot on Telegram now — send any message (e.g. 'hi'). The bot will reply with a pairing code."
2. Ask the user to paste the pairing code (a short hex string like 25255d).
3. Read ~/.claude/channels/telegram-<agent-name>/access.json to find the pending entry matching that code.
4. Extract the senderId from the pending entry.
5. Add the senderId to the allowFrom array and remove it from pending.
6. Write the updated access.json.
7. Create the approval notification: mkdir -p ~/.claude/channels/telegram-<agent-name>/approved then write the senderId to ~/.claude/channels/telegram-<agent-name>/approved/<senderId>. The bot polls this directory and sends a "Paired!" confirmation to the user.
8. Tell the user they're paired — the bot will now respond to their DMs.

Do not rely on /telegram:access pair for per-agent setups. That command reads ~/.claude/channels/telegram/access.json instead of the per-agent directory. For isolated bots, pair by editing the per-agent access.json directly.

If the user doesn't have the code yet or the pending entry hasn't appeared, wait a moment and re-read the file. The bot writes the pending entry when it receives the first DM.

If no, leave AGENT_CHANNEL="" and TELEGRAM_STATE_DIR commented out in config/agent.env — tmux-only mode is valid.

Step 4: Hooks (required)

Hooks are required for daily logs, compaction safety, and indexing.

1. Ensure .claude/settings.json exists
2. Ensure it contains the required hooks listed in Step 0
3. If not, overwrite it from templates/settings.json
4. Confirm to the user that hooks are installed/repaired

Step 5: launchd scheduling (optional, macOS only)

Ask: "Do you want automatic heartbeats, session logging, memory promotion, nightly self-improvement, and watchdog restarts via launchd?"

If yes:

1. Read the chosen session name and project directory
2. Generate plists from templates/launchd/ by replacing:
   • {{AGENT_SESSION_NAME}}
   • {{PROJECT_DIR}}
   • {{AGENT_CHANNEL}}
3. Write them to ~/Library/LaunchAgents/
4. Validate them with plutil -lint
5. Unload old versions if present, then launchctl load the new ones
6. Verify with launchctl list | grep <session>
7. If the assistant job exits with Operation not permitted or exit code 126, tell the user to grant Full Disk Access to /bin/bash in System Settings → Privacy & Security → Full Disk Access. Until then, they should start the agent manually after reboot.

If no, skip — the agent still works, but recurring tasks must be run manually or via /loop.

Step 6: Start the agent

./bin/start-agent.sh

Then verify the tmux session reaches the ❯ prompt. If Claude shows the workspace trust prompt, accept it and re-check the pane. If it shows "Channels are not currently available," go back to Step 3 prerequisite 1.

Step 7: Verify

• Check tmux session exists: tmux has-session -t <session>
• Check .claude/settings.json exists and includes the required hooks
• Capture the tmux pane and confirm you see:
  • Listening for channel messages from: plugin:telegram@... (if Telegram enabled)
  • ❯ prompt (session is ready)
  • No "Channels are not currently available" warning
• If launchd was enabled, verify the jobs are loaded: launchctl list | grep <session>

Step 8: Confirm

Tell the user:

• how to attach: tmux attach -t <session>
• which recurring tasks are automatic vs manual
• that hooks are installed and daily logs/memory promotion will work
• if Telegram is set up, confirm the pairing worked and the bot responds