Skip to content

OPERATIONS-GUIDE.md

Latest commit

 

History

History
1082 lines (774 loc) · 26.6 KB

OPERATIONS-GUIDE.md

File metadata and controls

1082 lines (774 loc) · 26.6 KB

Operations Guide: AI Maestro

Version: 1.0.0 Last Updated: 2025-10-09 Phase: 1 - Local Agents with Full UI Management

Overview

This guide explains how to create and manage AI coding agents using the AI Maestro dashboard. Works with Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor, Aider, and any other terminal-based AI agent. The dashboard automatically discovers existing agents from tmux ls and provides full agent management (create, rename, delete) directly from the UI!

Prerequisites Checklist

Before starting, ensure you have:

  • ✅ macOS with all requirements installed (see REQUIREMENTS.md)
  • ✅ tmux installed and working (tmux -V)
  • ✅ Your AI agent installed: Claude Code, Aider, Copilot CLI, Cursor, etc.
  • ✅ AI agent authenticated (e.g., claude login, aider --check, etc.)
  • ✅ Dashboard installed (yarn install completed)

1. Quick Start: Your First Agent

Step 1: Create an Agent

# Navigate to your project directory
cd ~/projects/my-app

# Create an agent (this starts a tmux session for it)
tmux new-session -s my-app-dev

# You're now inside tmux - your prompt should show a green bar at bottom

Step 2: Start Your AI Tool

# Inside the tmux session, start your AI assistant
# Choose one:
claude              # Claude Code
aider               # Aider AI
copilot             # GitHub Copilot CLI
cursor              # Cursor AI
# or any other terminal-based AI tool

# Your AI agent will initialize
# You can now start coding with AI assistance

Step 3: Detach from tmux

# Press: Ctrl+B, then D (hold Ctrl+B, release, then press D)
# This detaches from tmux but keeps the agent running

# You'll return to your normal terminal
# The tmux session continues running in the background

Step 4: Start the Dashboard

# In a new terminal window, navigate to the dashboard
cd /Users/juanpelaez/23blocks/webApps/agents-web

# Start the dashboard
yarn dev

# Wait for: "ready - started server on 0.0.0.0:23000"

⚠️ Network Access Warning: By default, AI Maestro is accessible on your local network at port 23000. This means anyone on your WiFi can access it. See the Security section for important information.

Step 5: Open the Dashboard

# Open in your default browser
open http://localhost:23000

# Or manually visit: http://localhost:23000

# From another device on your network (tablet, phone, etc.)
# Visit: http://YOUR-LOCAL-IP:23000
# To find your local IP: ifconfig | grep "inet " | grep -v 127.0.0.1

🎉 Success! You should see "my-app-dev" in the sidebar. Click it to view the terminal.

2. Agent Naming Best Practices

The dashboard automatically organizes agents hierarchically using forward slashes in names. This creates a beautiful, color-coded sidebar!

Hierarchical Naming Pattern (RECOMMENDED)

Use forward slashes to create 3-level organization:

# Format: category/subcategory/agent-name
fluidmind/agents/backend-architect
fluidmind/agents/frontend-developer
fluidmind/experiments/api-tester

ecommerce/development/cart-api
ecommerce/development/checkout-flow
ecommerce/testing/integration-tests

personal/projects/blog-redesign
personal/learning/rust-tutorial

Result in Dashboard:

  • Level 1 (category): "fluidmind" - Gets a unique color and icon
  • Level 2 (subcategory): "agents" - Folder under category
  • Level 3 (agent): "backend-architect" - Individual terminal

Alternative: Simple Names

# Pattern: project-purpose
tmux new-session -s ecommerce-api
tmux new-session -s blog-frontend

# These appear under "default" category

Naming Rules

  • ✅ Use forward slashes for hierarchy (category/sub/name)
  • ✅ Use lowercase letters, numbers, hyphens, underscores
  • ✅ Keep names descriptive and meaningful
  • ✅ Same category name = same color (automatic!)
  • ❌ Avoid spaces (use hyphens instead)
  • ❌ Avoid special characters (!, @, #, etc.)
  • ❌ More than 3 levels (category/sub1/sub2/name)

3. UI-Based Agent Management

You can now manage agents directly from the dashboard UI!

Create a New Agent (From UI)

  1. Click the "+" (Create) button in the sidebar header
  2. Enter agent name (use forward slashes for hierarchy)
  3. Optionally specify working directory
  4. Click "Create Agent"
  5. Agent appears immediately in sidebar

Example:

  • Name: fluidmind/agents/api-developer
  • Working Dir: /Users/you/projects/api

Rename an Agent (From UI)

  1. Hover over any agent in the sidebar
  2. Click the Edit icon that appears
  3. Enter new name
  4. Click "Rename"
  5. Dashboard updates immediately

Delete an Agent (From UI)

  1. Hover over any agent in the sidebar
  2. Click the Delete icon that appears
  3. Confirm deletion in modal
  4. Agent is terminated and removed

Warning: Deletion is permanent and cannot be undone!

4. Command-Line Agent Management

You can also manage agents via terminal commands:

List All Agents

# Show all running agents (via tmux)
tmux list-sessions
# or shorthand:
tmux ls

# Example output:
# fluidmind/agents/backend: 1 windows (created Wed Jan 10 14:23:45 2025)
# ecommerce/api: 1 windows (created Wed Jan 10 15:10:12 2025)

Attach to an Agent

# Attach to a specific agent
tmux attach-session -t "fluidmind/agents/backend"
# or shorthand:
tmux a -t "fluidmind/agents/backend"

# Note: Use quotes for names with slashes!

Kill an Agent

# Kill a specific agent (CAUTION: Permanent!)
tmux kill-session -t "my-app-dev"

# Kill all agents (CAUTION!)
tmux kill-server

Rename an Agent

# From inside the agent:
# Press Ctrl+B, then $
# Type new name and press Enter

# From outside the agent:
tmux rename-session -t "old-name" "new-name"

4. Working with Multiple Agents

Create Multiple Agents

# Create first agent (with Claude)
cd ~/projects/frontend
tmux new-session -s frontend-dev -d
tmux send-keys -t frontend-dev 'claude' C-m  # or aider, cursor, copilot, etc.

# Create second agent (with Aider)
cd ~/projects/backend
tmux new-session -s backend-api -d
tmux send-keys -t backend-api 'aider' C-m

# Create third agent (with Copilot)
cd ~/projects/database
tmux new-session -s db-migration -d
tmux send-keys -t db-migration 'copilot' C-m

# All three agents are now running in background
# Dashboard will show all three

Switch Between Agents in Dashboard

  1. Open dashboard: http://localhost:23000
  2. Click any agent name in the left sidebar
  3. Terminal content updates instantly
  4. Previous agents keep running in background

5. Agent Lifecycle

Agent States

Active 🟢

  • AI agent is running
  • You or dashboard is interacting with it
  • Terminal is responsive

Idle 🟡

  • Agent running but no recent activity
  • AI tool still active
  • Safe to interact

Ended ⚪

  • Agent was terminated (tmux session killed)
  • AI tool exited
  • Appears in dashboard until refresh

Typical Workflow

# Morning: Start agents
cd ~/projects/app-a && tmux new -s app-a -d && tmux send-keys -t app-a 'claude' C-m
cd ~/projects/app-b && tmux new -s app-b -d && tmux send-keys -t app-b 'aider' C-m

# Start dashboard
cd ~/agents-web && yarn dev

# Work throughout the day using the dashboard

# Evening: Review what's running
tmux ls

# Keep agents running overnight (optional)
# Or clean up:
tmux kill-session -t app-a
tmux kill-session -t app-b

6. Automation Scripts

Helper: Start Agent with AI Tool

Save as ~/bin/start-ai-session:

#!/bin/bash

# Usage: start-ai-session <agent-name> <ai-command> [directory]
# Example: start-ai-session my-project claude ~/projects/app
# Example: start-ai-session backend aider ~/projects/api

SESSION_NAME=$1
AI_COMMAND=${2:-claude}  # Default to claude if not specified
WORK_DIR=${3:-$(pwd)}

if [ -z "$SESSION_NAME" ]; then
    echo "Usage: start-ai-session <agent-name> <ai-command> [directory]"
    echo "Example: start-ai-session my-project claude ~/projects/app"
    echo "AI commands: claude, aider, copilot, cursor, etc."
    exit 1
fi

# Check if agent already exists
if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
    echo "❌ Agent '$SESSION_NAME' already exists"
    echo "   Attach: tmux a -t $SESSION_NAME"
    exit 1
fi

# Create agent in background
cd "$WORK_DIR"
tmux new-session -d -s "$SESSION_NAME" -c "$WORK_DIR"

# Start AI tool in the agent
tmux send-keys -t "$SESSION_NAME" "$AI_COMMAND" C-m

echo "✅ Agent '$SESSION_NAME' created with $AI_COMMAND"
echo "   Directory: $WORK_DIR"
echo "   View in dashboard: http://localhost:23000"
echo "   Attach manually: tmux a -t $SESSION_NAME"

Make executable:

chmod +x ~/bin/start-ai-session

# Add ~/bin to PATH in ~/.zshrc or ~/.bash_profile:
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Usage:

# Start agent with Claude in current directory
start-ai-session my-project claude

# Start agent with Aider in specific directory
start-ai-session api-work aider ~/projects/api

# Start multiple agents with different AI tools
start-ai-session frontend claude ~/projects/web
start-ai-session backend aider ~/projects/api
start-ai-session mobile cursor ~/projects/app

Helper: List Active Agents

Save as ~/bin/list-ai-agents:

#!/bin/bash

echo "🎯 Active AI Agents:"
echo ""

if ! tmux has-session 2>/dev/null; then
    echo "No active agents"
    exit 0
fi

tmux list-sessions -F '#{session_name} | Created: #{session_created_string} | Windows: #{session_windows}' | \
while IFS='|' read -r name created windows; do
    echo "📁 $name"
    echo "   $created"
    echo "   $windows"
    echo ""
done

echo "💡 Tip: View all agents in dashboard at http://localhost:23000"

Make executable and run:

chmod +x ~/bin/list-ai-agents
list-ai-agents

Helper: Kill All Agents

Save as ~/bin/cleanup-ai-agents:

#!/bin/bash

echo "🧹 Cleaning up AI agents..."

if ! tmux has-session 2>/dev/null; then
    echo "No active agents to clean up"
    exit 0
fi

# List agents
echo ""
echo "Current agents:"
tmux ls

echo ""
read -p "Kill ALL agents? (yes/no): " CONFIRM

if [ "$CONFIRM" = "yes" ]; then
    tmux kill-server
    echo "✅ All agents terminated"
else
    echo "❌ Cancelled"
fi

Make executable:

chmod +x ~/bin/cleanup-ai-agents

7. Agent Notes Feature

Each agent has a built-in notes area for capturing important information while working with your AI agent.

Using Agent Notes

  1. Expand Notes: Click "Show Agent Notes" button below the terminal (if collapsed)
  2. Take Notes: Type directly in the textarea - supports copy/paste
  3. Auto-Save: Notes save automatically to localStorage (per-agent)
  4. Collapse: Click the down arrow to hide notes and maximize terminal space

Notes Use Cases

  • Track decisions: Record architectural decisions made with your AI agent
  • Save commands: Copy/paste useful commands your AI suggests
  • Todo lists: Keep track of what's left to implement
  • Context: Notes for when you return to the agent later
  • Code snippets: Temporary storage for code before committing

Note: Notes are stored in browser localStorage and persist between dashboard restarts!

8. Dashboard Operations

Starting the Dashboard

# Navigate to dashboard directory
cd /Users/juanpelaez/23blocks/webApps/agents-web

# Development mode (with hot reload)
yarn dev

# Production mode (with PM2 for auto-restart)
yarn build
pm2 start ecosystem.config.js

# Custom port and hostname
PORT=3001 yarn dev
HOSTNAME=localhost PORT=3001 yarn dev  # Localhost-only for better security

# Run localhost-only (more secure, not accessible on network)
HOSTNAME=localhost yarn dev

Accessing the Dashboard

# Default URL (from same machine)
open http://localhost:23000

# From another device on your local network
# 1. Find your local IP address:
ifconfig | grep "inet " | grep -v 127.0.0.1
# Example output: inet 10.0.0.87 ...

# 2. On your other device (tablet, phone, another computer):
# Visit: http://10.0.0.87:23000
# (Replace 10.0.0.87 with your actual local IP)

# Custom port
open http://localhost:3001

Security

⚠️ Important: By default, AI Maestro is accessible from any device on your local network:

  • ✅ Convenient - Access from tablets, phones, other computers
  • ⚠️ No authentication - Anyone on your WiFi can access it
  • ⚠️ Unencrypted - WebSocket connections use ws:// (not wss://)
  • ⚠️ Full terminal access - Anyone connected can run commands

Safe for:

  • Home networks (trusted WiFi)
  • Private office networks
  • Development on trusted LANs

NOT safe for:

  • Public WiFi (coffee shops, airports)
  • Shared office WiFi with untrusted users
  • Exposing to the internet

To run localhost-only (more secure):

HOSTNAME=localhost PORT=3000 yarn dev

See SECURITY.md for full security details.

Stopping the Dashboard

# If running with yarn dev: Press Ctrl+C in the terminal

# If running with PM2:
pm2 stop ai-maestro
pm2 delete ai-maestro  # To remove from PM2 completely

# If running in background, find and kill the process:
lsof -i :23000
kill -9 <PID>

8. SSH Configuration for Git Operations

The Problem

When working with AI agents in tmux (especially after system restarts), you may encounter:

git@gitlab.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Root cause: The SSH agent socket path (SSH_AUTH_SOCK) changes between system restarts. tmux sessions started at boot don't inherit the updated socket path.

The Solution: Stable SSH Symlink

Create a stable symlink that tmux always uses, which your shell keeps updated with the current SSH agent socket.

One-Time Setup

Step 1: Configure tmux to use a stable symlink

Add to ~/.tmux.conf:

# SSH Agent Configuration - AI Maestro
# This tells tmux to use a stable symlink instead of the changing socket path
set-option -g update-environment "DISPLAY SSH_ASKPASS SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY"
set-environment -g 'SSH_AUTH_SOCK' ~/.ssh/ssh_auth_sock

Step 2: Configure your shell to maintain the symlink

Add to ~/.zshrc (or ~/.bashrc if using bash):

# SSH Agent for tmux - AI Maestro
# Create/update stable symlink to current SSH agent socket
if [ -S "$SSH_AUTH_SOCK" ] && [ ! -h "$SSH_AUTH_SOCK" ]; then
    mkdir -p ~/.ssh
    ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
fi

Step 3: Apply the configuration

# Create initial symlink
mkdir -p ~/.ssh && ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock

# Reload tmux configuration
tmux source-file ~/.tmux.conf

# Reload shell configuration (or open new terminal)
source ~/.zshrc

How It Works

  1. SSH Agent creates a socket at /private/tmp/com.apple.launchd.XXXXX/Listeners (path changes on restart)
  2. Your shell keeps ~/.ssh/ssh_auth_sock symlinked to the current socket
  3. tmux sessions use the stable ~/.ssh/ssh_auth_sock path
  4. Result: Git/SSH operations work in all tmux sessions, even after restarts

Verifying It Works

Test in a new tmux session:

# Create test agent
tmux new-session -s test-ssh -d

# Test SSH
tmux send-keys -t test-ssh 'ssh-add -l' C-m
sleep 1
tmux capture-pane -t test-ssh -p | tail -5

# Should show your SSH keys
# Clean up
tmux kill-session -t test-ssh

Or test directly:

# Should show your SSH keys
SSH_AUTH_SOCK=~/.ssh/ssh_auth_sock ssh-add -l

# Should authenticate successfully
SSH_AUTH_SOCK=~/.ssh/ssh_auth_sock ssh -T git@github.com

Fixing Existing Sessions

If you have tmux sessions that were created before this setup, they'll still have the old SSH config. Two options:

Option 1: Restart the shell (quick)

# In AI Maestro terminal or attached tmux session
exec $SHELL

# Then test
git push  # Should work now

Option 2: Create new agents

New agents from AI Maestro will automatically have SSH configured correctly.

Troubleshooting SSH Issues

Problem: SSH still not working in tmux

  1. Verify symlink exists and points to correct socket:

    ls -la ~/.ssh/ssh_auth_sock
# Should show symlink to /private/tmp/com.apple.launchd.*/Listeners

  2. Verify tmux is using the symlink:

    tmux show-environment | grep SSH_AUTH_SOCK
# Should show: SSH_AUTH_SOCK=/Users/you/.ssh/ssh_auth_sock

  3. Recreate the symlink:

    rm ~/.ssh/ssh_auth_sock
ln -sf "$SSH_AUTH_SOCK" ~/.ssh/ssh_auth_sock
tmux source-file ~/.tmux.conf

  4. Check SSH agent is running:

    ssh-add -l
# Should list your keys, not "Could not open a connection"

Problem: Works in terminal but not in AI Maestro

This means the shell environment in your tmux session needs refreshing:

# In the AI Maestro terminal
exec $SHELL

Problem: SSH works but git still fails

Check your git remote URL:

git remote -v

# Should use SSH format:
# origin  git@github.com:user/repo.git (fetch)

# NOT HTTPS format:
# origin  https://github.com/user/repo.git (fetch)

# Fix if needed:
git remote set-url origin git@github.com:user/repo.git

9. Troubleshooting

Services Not Running After Restart (MOST COMMON)

Problem: After restarting your Mac, the dashboard shows "Socket Error" or "Cannot connect" when trying to create agents.

Cause: The tmux server is not running. tmux sessions don't survive system restarts by default.

Immediate Fix:

# Create a tmux session to start the tmux server
tmux new-session -s default -d

# Now refresh your dashboard - it should work

Permanent Fix - Auto-start tmux on Login:

Create a LaunchAgent to automatically start tmux after every restart:

# 1. Find your tmux path
which tmux
# Output example: /opt/homebrew/bin/tmux

# 2. Create the LaunchAgent directory (if it doesn't exist)
mkdir -p ~/Library/LaunchAgents

# 3. Create the LaunchAgent file
cat > ~/Library/LaunchAgents/com.user.tmux.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.tmux</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/tmux</string>
        <string>new-session</string>
        <string>-d</string>
        <string>-s</string>
        <string>default</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>StandardOutPath</key>
    <string>/tmp/tmux-launchagent.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/tmux-launchagent.error.log</string>
</dict>
</plist>
EOF

# 4. Update the tmux path in the file if yours is different
# Edit the file and replace /opt/homebrew/bin/tmux with your path from step 1

# 5. Load the LaunchAgent
launchctl load ~/Library/LaunchAgents/com.user.tmux.plist

# 6. Verify it's running
tmux ls
# Should show: default: 1 windows (created ...)

Permanent Fix - Auto-start Dashboard with pm2:

Configure pm2 to auto-start your dashboard on every restart:

# 1. Generate the pm2 startup script
pm2 startup
# This will output a sudo command - copy and run it

# 2. Save your current pm2 processes
pm2 save

# 3. Verify pm2 LaunchAgent was created
ls ~/Library/LaunchAgents/ | grep pm2
# Should show: pm2.yourusername.plist

Verify Both Services:

# Check tmux is running
tmux ls

# Check pm2 is running
pm2 list

# Check LaunchAgents are loaded
launchctl list | grep tmux
launchctl list | grep pm2

Now after every restart, both tmux and your dashboard will start automatically!

⚠️ Important: After setting up auto-start, also configure SSH for git operations. See Section 8: SSH Configuration for detailed setup to avoid "Permission denied (publickey)" errors.

Git/SSH Permission Denied Errors

Problem: Getting git@gitlab.com: Permission denied (publickey) errors in tmux sessions.

Solution: This is an SSH configuration issue. Follow the comprehensive guide in Section 8: SSH Configuration for Git Operations.

Quick fix for existing agents:

# In AI Maestro terminal
exec $SHELL

Agent Not Appearing in Dashboard

Problem: Created an agent but it doesn't show in the dashboard.

Solution:

# 1. Verify agent exists
tmux ls

# 2. Refresh dashboard in browser (Cmd+R or F5)

# 3. Check dashboard logs for errors
# Look in the terminal where you ran `yarn dev`

# 4. Restart dashboard
# Press Ctrl+C, then run `yarn dev` again

Can't Connect to Agent in Dashboard

Problem: Agent appears in list but clicking it shows "Connection Error"

Solution:

# 1. Verify tmux session is actually running
tmux ls

# 2. Try attaching manually
tmux attach -t <agent-name>

# 3. If agent is frozen, kill and recreate it
tmux kill-session -t <agent-name>
start-ai-session <agent-name> claude  # or your preferred AI tool

# 4. Check dashboard WebSocket connection
# Open browser console (F12) and look for errors

Terminal Not Responsive

Problem: Can see the terminal but typing doesn't work

Solution:

# 1. Click directly in the terminal area to focus it

# 2. Refresh the browser page

# 3. Check if your AI tool is still running in tmux:
tmux attach -t <agent-name>
# If your AI exited, restart it:
claude  # or aider, cursor, copilot, etc.

# 4. Check browser console for JavaScript errors

Dashboard Won't Start

Problem: yarn dev fails with errors

Solution:

# 1. Check if port 23000 is in use
lsof -i :23000
kill -9 <PID>

# 2. Reinstall dependencies
rm -rf node_modules yarn.lock
yarn install

# 3. Check Node.js version
node --version  # Should be v18.17+ or v20.x

# 4. Try a different port
PORT=3001 yarn dev

Agent Names Look Weird

Problem: Agent names contain strange characters or are too long

Solution:

# Rename the agent
tmux rename-session -t old-name new-clean-name

# Use proper naming conventions (see Section 2)

9. Best Practices

Agent Organization

# Group related agents with prefixes
tmux new -s project-frontend
tmux new -s project-backend
tmux new -s project-database

# Use descriptive names that explain the task
tmux new -s fix-auth-bug      # ✅ Good
tmux new -s test              # ❌ Too vague

# One agent per distinct task or context

Resource Management

# Check how many agents you're running
tmux ls | wc -l

# Keep it reasonable (5-10 active agents max)
# Kill agents you're done with
tmux kill-session -t completed-task

Backup Important Agents

# Capture terminal content before killing agent
tmux capture-pane -pt <agent-name> -S - > ~/backups/agent-backup.txt

# Or ask your AI tool to save the conversation
# (e.g., "Please summarize our conversation and save it")

Daily Workflow

# Morning routine
cd ~/agents-web && yarn dev &           # Start dashboard
start-ai-session main-work claude ~/projects
start-ai-session experiments aider ~/tests
open http://localhost:23000             # Open dashboard

# Evening routine
list-ai-agents                          # Review active agents
cleanup-ai-agents                       # Kill all agents (optional)
# Or keep them running overnight

10. Advanced Tips

Auto-start Services on Boot

⚠️ Important: After a system restart, both tmux and the dashboard need to be running for AI Maestro to work.

For comprehensive setup instructions, see the "Services Not Running After Restart" section in Troubleshooting (Section 8).

Quick summary:

  • tmux auto-start: Create a LaunchAgent to start tmux server on login
  • Dashboard auto-start: Use pm2 startup and pm2 save to auto-start the dashboard
  • Verification: Both services will start automatically after every restart

Persistent Agents Across Reboots

Agents (tmux sessions) end when you restart your Mac. To persist them:

  1. tmux-resurrect plugin - Save and restore tmux sessions
  2. systemd user services (on Linux)
  3. Manual session recreation script (run after reboot)

Example restoration script ~/bin/restore-agents:

#!/bin/bash

# Restore common agents after reboot
start-ai-session main claude ~/projects/main
start-ai-session experiments aider ~/experiments
start-ai-session docs cursor ~/documentation

echo "✅ Agents restored"

11. Quick Reference Card

Essential Commands

# Agent Management
tmux new -s name              # Create agent
tmux ls                       # List agents
tmux a -t name                # Attach to agent
tmux kill-session -t name     # Kill agent

# Inside tmux
Ctrl+B, D                     # Detach
Ctrl+B, $                     # Rename agent
Ctrl+D                        # Exit AI tool (closes agent)

# Dashboard
yarn dev                      # Start dashboard
open http://localhost:23000   # Open dashboard
Ctrl+C                        # Stop dashboard
pm2 start ecosystem.config.js            # Start with PM2

# Helper Scripts (if created)
start-ai-session name agent   # Create agent with AI tool
list-ai-agents                # List all agents
cleanup-ai-agents             # Kill all agents

12. Next Steps

After mastering basic operations:

  1. 📖 Read UX-SPECIFICATIONS.md to understand all dashboard features
  2. 🏗️ Read TECHNICAL-SPECIFICATIONS.md for architecture details
  3. 🎨 Read FRONTEND-IMPLEMENTATION.md if modifying the UI
  4. 🚀 Explore Phase 2 features (agent creation from UI, remote agents)

Known Issues

AMP commands prompt for permission on every use

When agents use amp-read.sh or amp-reply.sh, Claude Code asks for permission each time. This also blocks the subconscious from automatically processing inbox messages since triggerMessageCheck() injects a prompt that includes "check your inbox."

Fix: Add AMP commands to the global allow list in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(amp-inbox.sh:*)",
      "Bash(amp-read.sh:*)",
      "Bash(amp-reply.sh:*)",
      "Bash(CLAUDE_AGENT_NAME=* amp-inbox.sh:*)",
      "Bash(CLAUDE_AGENT_NAME=* amp-read.sh:*)",
      "Bash(CLAUDE_AGENT_NAME=* amp-reply.sh:*)"
    ]
  }
}

If the file already has a permissions.allow array, merge these entries into it. This must be done on each machine where agents run.

Support

Questions or issues?

  • Check TROUBLESHOOTING.md
  • Review dashboard logs (terminal where yarn dev is running)
  • Check tmux logs: tmux list-sessions
  • Open an issue in the project repository

Happy coding with your AI agents! 🤖