--- name: tinyagi-admin description: "Manage and operate the TinyAGI system itself — agents, teams, settings, queue, tasks, daemon lifecycle, and source code. Use when the agent needs to: list/add/remove/update agents or teams, check queue status, view logs, start/stop/restart TinyAGI, change settings (provider, model, channels), send messages to the queue, manage tasks, retry dead-letter messages, view recent responses, modify TinyAGI source code or configuration, or perform any administrative operation on the TinyAGI platform. Triggers: 'manage tinyagi', 'add an agent', 'remove a team', 'check queue', 'view logs', 'restart tinyagi', 'change provider', 'update settings', 'create a task', 'modify tinyagi code'." --- # 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 ` — prompts `[y/N]` - `tinyagi team remove ` — prompts `[y/N]` - `tinyagi team remove-agent ` — 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: ```bash 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 "" # Send message to default agent tinyagi send "@agent_id " # Send to specific agent tinyagi reset [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 # Show agent config tinyagi agent provider # Set agent provider tinyagi agent provider --model tinyagi team list # List teams tinyagi team show # Show team config tinyagi team add-agent # Add agent to team (no prompts) tinyagi channel start # Start a channel tinyagi channel stop # Stop a channel tinyagi channel restart # Restart a channel tinyagi channel reset # Reset channel auth tinyagi pairing list # Show all pairings tinyagi pairing pending # Show pending tinyagi pairing approved # Show approved tinyagi pairing approve

             # Approve a sender
tinyagi pairing unpair  
```

## 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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:

```bash
cd  && npm run build
```

Then restart the daemon to load changes:

```bash
tinyagi restart
```

## Workflow examples

### Add a new agent and assign to a team

```bash
# 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

```bash
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

```bash
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"}'
```