TinyAGI Admin

Operate and manage the TinyAGI multi-agent system. This skill covers both runtime administration (via the REST API) and source code modification.

Important paths

• TinyAGI home (runtime data): ~/.tinyagi/
  • settings.json — all configuration (agents, teams, channels, models, workspace)
  • tinyagi.db — SQLite queue database
  • tasks.json — Kanban tasks
  • pairing.json — sender allowlist
  • logs/ — queue, daemon, and channel logs
  • chats/ — team chain chat history
  • events/ — real-time event files
  • plugins/ — plugin directory
• TinyAGI source code: the repo where this skill is installed (check git rev-parse --show-toplevel or look for tinyagi.sh in parent dirs)
• Agent workspaces: configured in settings.json under workspace.path (default: ~/tinyagi-workspace/{agent_id}/)

Interactivity warning

Many tinyagi CLI commands are interactive (prompt for user input). Do NOT run these directly:

• tinyagi setup — fully interactive wizard
• tinyagi agent add — prompts for all fields
• tinyagi team add — prompts for all fields
• tinyagi agent remove <id> — prompts [y/N]
• tinyagi team remove <id> — prompts [y/N]
• tinyagi team remove-agent <t> <a> — may prompt for new leader + [y/N]

Instead, use the REST API or direct settings.json edits (see below).

Non-interactive CLI commands (safe to run)

These CLI commands accept all parameters as arguments and do not prompt:

tinyagi start                              # Start daemon
tinyagi stop                               # Stop all processes
tinyagi restart                            # Restart daemon
tinyagi status                             # Show status
tinyagi logs [queue|discord|telegram|whatsapp|heartbeat|daemon|all]
tinyagi send "<message>"                   # Send message to default agent
tinyagi send "@agent_id <message>"         # Send to specific agent
tinyagi reset <agent_id> [agent_id...]     # Reset agent conversations
tinyagi provider anthropic                 # Switch global provider
tinyagi provider openai --model gpt-5.3-codex
tinyagi model sonnet                       # Switch global model
tinyagi agent list                         # List agents
tinyagi agent show <id>                    # Show agent config
tinyagi agent provider <id> <provider>     # Set agent provider
tinyagi agent provider <id> <provider> --model <model>
tinyagi team list                          # List teams
tinyagi team show <id>                     # Show team config
tinyagi team add-agent <team_id> <agent_id>  # Add agent to team (no prompts)
tinyagi channel start <channel>            # Start a channel
tinyagi channel stop <channel>             # Stop a channel
tinyagi channel restart <channel>          # Restart a channel
tinyagi channel reset <channel>            # Reset channel auth
tinyagi pairing list                       # Show all pairings
tinyagi pairing pending                    # Show pending
tinyagi pairing approved                   # Show approved
tinyagi pairing approve <code>             # Approve a sender
tinyagi pairing unpair <channel> <sender_id>

REST API (preferred for programmatic operations)

The API server runs on http://localhost:3777 (configurable via TINYAGI_API_PORT). The API server is available when TinyAGI is running.

Agents

# List agents
curl -s http://localhost:3777/api/agents | jq

# Create or update agent (non-interactive, auto-provisions workspace)
curl -s -X PUT http://localhost:3777/api/agents/coder \
  -H 'Content-Type: application/json' \
  -d '{"name":"Coder","provider":"anthropic","model":"sonnet"}'

# Create agent with a system prompt (written to AGENTS.md in workspace on provisioning)
curl -s -X PUT http://localhost:3777/api/agents/coder \
  -H 'Content-Type: application/json' \
  -d '{"name":"Coder","provider":"anthropic","model":"sonnet","system_prompt":"You are a senior engineer. Always write tests."}'

# Optional fields: working_directory, system_prompt, prompt_file

# Delete agent
curl -s -X DELETE http://localhost:3777/api/agents/coder

Teams

# List teams
curl -s http://localhost:3777/api/teams | jq

# Create or update team
curl -s -X PUT http://localhost:3777/api/teams/dev \
  -H 'Content-Type: application/json' \
  -d '{"name":"Dev Team","agents":["coder","reviewer"],"leader_agent":"coder"}'

# Delete team
curl -s -X DELETE http://localhost:3777/api/teams/dev

Settings

# Get full settings
curl -s http://localhost:3777/api/settings | jq

# Update settings (shallow merge)
curl -s -X PUT http://localhost:3777/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"monitoring":{"heartbeat_interval":1800}}'

Services (channels & daemon)

# Start a channel
curl -s -X POST http://localhost:3777/api/services/channel/telegram/start

# Stop a channel
curl -s -X POST http://localhost:3777/api/services/channel/telegram/stop

# Restart a channel
curl -s -X POST http://localhost:3777/api/services/channel/telegram/restart

# Start all enabled channels
curl -s -X POST http://localhost:3777/api/services/apply

# Restart the entire process (exit code 75 triggers restart loop in Docker)
curl -s -X POST http://localhost:3777/api/services/restart

Messages

# Send message to queue (processed by agent)
curl -s -X POST http://localhost:3777/api/message \
  -H 'Content-Type: application/json' \
  -d '{"message":"@coder fix the login bug","sender":"Admin","channel":"api"}'

Queue

# Queue status
curl -s http://localhost:3777/api/queue/status | jq

# Recent responses
curl -s http://localhost:3777/api/responses?limit=10 | jq

# Dead-letter messages
curl -s http://localhost:3777/api/queue/dead | jq

# Retry a dead message
curl -s -X POST http://localhost:3777/api/queue/dead/123/retry

# Delete a dead message
curl -s -X DELETE http://localhost:3777/api/queue/dead/123

Tasks

# List tasks
curl -s http://localhost:3777/api/tasks | jq

# Create task
curl -s -X POST http://localhost:3777/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"Fix auth bug","description":"Login fails on mobile","status":"backlog","assignee":"coder","assigneeType":"agent"}'

# Update task
curl -s -X PUT http://localhost:3777/api/tasks/TASK_ID \
  -H 'Content-Type: application/json' \
  -d '{"status":"in-progress"}'

# Delete task
curl -s -X DELETE http://localhost:3777/api/tasks/TASK_ID

Logs

# Recent queue logs
curl -s http://localhost:3777/api/logs?limit=50 | jq

Direct settings.json editing

When the API server is not running, edit ~/.tinyagi/settings.json directly. Use jq for safe atomic edits:

SETTINGS="$HOME/.tinyagi/settings.json"

# Add an agent
jq --arg id "analyst" --argjson agent '{"name":"Analyst","provider":"anthropic","model":"sonnet","working_directory":"'$HOME'/tinyagi-workspace/analyst"}' \
  '.agents[$id] = $agent' "$SETTINGS" > "$SETTINGS.tmp" && mv "$SETTINGS.tmp" "$SETTINGS"

# Remove an agent
jq 'del(.agents["analyst"])' "$SETTINGS" > "$SETTINGS.tmp" && mv "$SETTINGS.tmp" "$SETTINGS"

# Add a team
jq --arg id "research" --argjson team '{"name":"Research Team","agents":["analyst","writer"],"leader_agent":"analyst"}' \
  '.teams //= {} | .teams[$id] = $team' "$SETTINGS" > "$SETTINGS.tmp" && mv "$SETTINGS.tmp" "$SETTINGS"

After editing settings.json, run tinyagi restart to pick up changes.

Modifying TinyAGI source code

When modifying TinyAGI's own code (features, bug fixes, new routes, etc.):

• Monorepo packages:
  • packages/core/src/ — shared utilities (config, db, logging, types, plugins, agent invocation)
  • packages/server/src/ — API server (Hono framework)
  • packages/server/src/routes/ — route handlers (agents, teams, settings, queue, tasks, messages, logs, services)
  • packages/main/src/ — entry point, queue processor, channel/heartbeat lifecycle
  • packages/cli/src/ — CLI modules (daemon, channel, install, logs, agent, team, provider, etc.)
  • packages/cli/bin/tinyagi.mjs — thin CLI dispatcher (delegates to compiled modules in dist/)
  • packages/teams/src/ — team orchestration
  • packages/visualizer/src/ — TUI dashboards (team visualizer, chatroom viewer)
• Skills: .agents/skills/ — skill definitions (copied to agent workspaces on provision)
• Web portal: tinyoffice/ — Next.js app
• Docker: Dockerfile, docker-entrypoint.sh, docker-compose.yml

After modifying TypeScript source, rebuild:

cd <tinyagi-repo> && npm run build

Then restart the daemon to load changes:

tinyagi restart

Workflow examples

Add a new agent and assign to a team

# 1. Create agent via API
curl -s -X PUT http://localhost:3777/api/agents/reviewer \
  -H 'Content-Type: application/json' \
  -d '{"name":"Code Reviewer","provider":"anthropic","model":"sonnet"}'

# 2. Add to existing team (non-interactive CLI)
tinyagi team add-agent dev reviewer

Check system health

tinyagi status
curl -s http://localhost:3777/api/queue/status | jq
curl -s http://localhost:3777/api/queue/dead | jq
tinyagi logs queue

Create a task and assign to agent

curl -s -X POST http://localhost:3777/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"Review PR #42","status":"backlog","assignee":"reviewer","assigneeType":"agent"}'