Metadata-Version: 2.4
Name: tag-agent
Version: 0.7.1
Summary: Orchestrate AI agents from your terminal — multi-source credential import, swarm topology, background queue, live dashboard
Author: Nous Research
License-Expression: MIT
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==2.24.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: fire==0.7.1
Requires-Dist: httpx[socks]==0.28.1
Requires-Dist: rich==14.3.3
Requires-Dist: tenacity==9.1.4
Requires-Dist: pyyaml==6.0.3
Requires-Dist: ruamel.yaml==0.18.17
Requires-Dist: requests==2.33.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: pydantic==2.13.4
Requires-Dist: prompt_toolkit==3.0.52
Requires-Dist: croniter==6.0.0
Requires-Dist: Markdown==3.10.2
Requires-Dist: PyJWT[crypto]==2.12.1
Requires-Dist: tzdata==2025.3; sys_platform == "win32"
Requires-Dist: psutil==7.2.2
Requires-Dist: pathspec==1.1.1
Requires-Dist: fastapi<1,>=0.104.0
Requires-Dist: uvicorn[standard]<1,>=0.24.0
Requires-Dist: ptyprocess<1,>=0.7.0; sys_platform != "win32"
Requires-Dist: pywinpty<3,>=2.0.0; sys_platform == "win32"
Requires-Dist: Pillow==12.2.0
Provides-Extra: anthropic
Requires-Dist: anthropic==0.86.0; extra == "anthropic"
Provides-Extra: exa
Requires-Dist: exa-py==2.10.2; extra == "exa"
Provides-Extra: firecrawl
Requires-Dist: firecrawl-py==4.17.0; extra == "firecrawl"
Provides-Extra: parallel-web
Requires-Dist: parallel-web==0.4.2; extra == "parallel-web"
Provides-Extra: fal
Requires-Dist: fal-client==0.13.1; extra == "fal"
Provides-Extra: edge-tts
Requires-Dist: edge-tts==7.2.7; extra == "edge-tts"
Provides-Extra: modal
Requires-Dist: modal==1.3.4; extra == "modal"
Provides-Extra: daytona
Requires-Dist: daytona==0.155.0; extra == "daytona"
Provides-Extra: hindsight
Requires-Dist: hindsight-client==0.6.1; extra == "hindsight"
Provides-Extra: dev
Requires-Dist: debugpy==1.8.20; extra == "dev"
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: pytest-timeout==2.4.0; extra == "dev"
Requires-Dist: mcp==1.26.0; extra == "dev"
Requires-Dist: starlette==1.0.1; extra == "dev"
Requires-Dist: ty==0.0.21; extra == "dev"
Requires-Dist: ruff==0.15.10; extra == "dev"
Requires-Dist: setuptools==82.0.1; extra == "dev"
Provides-Extra: messaging
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "messaging"
Requires-Dist: discord.py[voice]==2.7.1; extra == "messaging"
Requires-Dist: aiohttp==3.13.3; extra == "messaging"
Requires-Dist: brotlicffi==1.2.0.1; extra == "messaging"
Requires-Dist: slack-bolt==1.27.0; extra == "messaging"
Requires-Dist: slack-sdk==3.40.1; extra == "messaging"
Requires-Dist: qrcode==7.4.2; extra == "messaging"
Provides-Extra: cron
Provides-Extra: slack
Requires-Dist: slack-bolt==1.27.0; extra == "slack"
Requires-Dist: slack-sdk==3.40.1; extra == "slack"
Requires-Dist: aiohttp==3.13.3; extra == "slack"
Provides-Extra: matrix
Requires-Dist: mautrix[encryption]==0.21.0; extra == "matrix"
Requires-Dist: aiosqlite==0.22.1; extra == "matrix"
Requires-Dist: asyncpg==0.31.0; extra == "matrix"
Requires-Dist: aiohttp-socks==0.11.0; extra == "matrix"
Provides-Extra: wecom
Requires-Dist: defusedxml==0.7.1; extra == "wecom"
Provides-Extra: cli
Requires-Dist: simple-term-menu==1.6.6; extra == "cli"
Provides-Extra: tts-premium
Requires-Dist: elevenlabs==1.59.0; extra == "tts-premium"
Provides-Extra: voice
Requires-Dist: faster-whisper==1.2.1; extra == "voice"
Requires-Dist: sounddevice==0.5.5; extra == "voice"
Requires-Dist: numpy==2.4.3; extra == "voice"
Provides-Extra: pty
Provides-Extra: honcho
Requires-Dist: honcho-ai==2.0.1; extra == "honcho"
Provides-Extra: vision
Provides-Extra: mcp
Requires-Dist: mcp==1.26.0; extra == "mcp"
Requires-Dist: starlette==1.0.1; extra == "mcp"
Provides-Extra: nemo-relay
Requires-Dist: nemo-relay==0.3; extra == "nemo-relay"
Provides-Extra: homeassistant
Requires-Dist: aiohttp==3.13.3; extra == "homeassistant"
Provides-Extra: sms
Requires-Dist: aiohttp==3.13.3; extra == "sms"
Provides-Extra: computer-use
Requires-Dist: mcp==1.26.0; extra == "computer-use"
Requires-Dist: starlette==1.0.1; extra == "computer-use"
Provides-Extra: acp
Requires-Dist: agent-client-protocol==0.9.0; extra == "acp"
Provides-Extra: mistral
Requires-Dist: mistralai==2.4.8; extra == "mistral"
Provides-Extra: bedrock
Requires-Dist: boto3==1.42.89; extra == "bedrock"
Provides-Extra: azure-identity
Requires-Dist: azure-identity==1.25.3; extra == "azure-identity"
Provides-Extra: termux
Requires-Dist: python-telegram-bot[webhooks]==22.6; extra == "termux"
Requires-Dist: hermes-agent[cron]; extra == "termux"
Requires-Dist: hermes-agent[cli]; extra == "termux"
Requires-Dist: hermes-agent[pty]; extra == "termux"
Requires-Dist: hermes-agent[mcp]; extra == "termux"
Requires-Dist: hermes-agent[honcho]; extra == "termux"
Requires-Dist: hermes-agent[acp]; extra == "termux"
Provides-Extra: termux-all
Requires-Dist: hermes-agent[termux]; extra == "termux-all"
Requires-Dist: hermes-agent[google]; extra == "termux-all"
Requires-Dist: hermes-agent[homeassistant]; extra == "termux-all"
Requires-Dist: hermes-agent[sms]; extra == "termux-all"
Requires-Dist: hermes-agent[web]; extra == "termux-all"
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream==0.24.3; extra == "dingtalk"
Requires-Dist: alibabacloud-dingtalk==2.2.42; extra == "dingtalk"
Requires-Dist: qrcode==7.4.2; extra == "dingtalk"
Provides-Extra: feishu
Requires-Dist: lark-oapi==1.5.3; extra == "feishu"
Requires-Dist: qrcode==7.4.2; extra == "feishu"
Provides-Extra: google
Requires-Dist: google-api-python-client==2.194.0; extra == "google"
Requires-Dist: google-auth-oauthlib==1.3.1; extra == "google"
Requires-Dist: google-auth-httplib2==0.3.1; extra == "google"
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api==1.2.4; extra == "youtube"
Provides-Extra: web
Requires-Dist: fastapi==0.133.1; extra == "web"
Requires-Dist: uvicorn[standard]==0.41.0; extra == "web"
Requires-Dist: starlette==1.0.1; extra == "web"
Provides-Extra: all
Requires-Dist: hermes-agent[cron]; extra == "all"
Requires-Dist: hermes-agent[cli]; extra == "all"
Requires-Dist: hermes-agent[pty]; extra == "all"
Requires-Dist: hermes-agent[mcp]; extra == "all"
Requires-Dist: hermes-agent[homeassistant]; extra == "all"
Requires-Dist: hermes-agent[sms]; extra == "all"
Requires-Dist: hermes-agent[acp]; extra == "all"
Requires-Dist: hermes-agent[google]; extra == "all"
Requires-Dist: hermes-agent[web]; extra == "all"
Requires-Dist: hermes-agent[youtube]; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/sanskarpan/tag-agent/main/docs/logo.svg" alt="TAG" width="120" />
</p>

<h1 align="center">TAG — Terminal Agent Gateway</h1>

<p align="center">
  <strong>Orchestrate AI agents from your terminal.<br/>Any model. Any provider. One CLI.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/tag-agent/"><img src="https://img.shields.io/pypi/v/tag-agent?style=flat-square&label=PyPI&color=3776AB" alt="PyPI" /></a>
  <a href="https://www.npmjs.com/package/tag-agent"><img src="https://img.shields.io/npm/v/tag-agent?style=flat-square&label=npm&color=CB3837" alt="npm" /></a>
  <a href="https://pypi.org/project/tag-agent/"><img src="https://img.shields.io/pypi/dm/tag-agent?style=flat-square&label=installs&color=brightgreen" alt="Downloads" /></a>
  <a href="https://pypi.org/project/tag-agent/"><img src="https://img.shields.io/pypi/pyversions/tag-agent?style=flat-square" alt="Python 3.11+" /></a>
  <a href="https://github.com/sanskarpan/tag-agent/actions"><img src="https://img.shields.io/github/actions/workflow/status/sanskarpan/tag-agent/ci.yml?branch=main&label=CI&style=flat-square" alt="CI" /></a>
  <a href="https://github.com/sanskarpan/tag-agent/blob/main/LICENSE"><img src="https://img.shields.io/github/license/sanskarpan/tag-agent?style=flat-square&color=blue" alt="MIT" /></a>
</p>

<p align="center">
  <a href="#install">Install</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#features">Features</a> •
  <a href="#command-reference">Commands</a> •
  <a href="#profiles">Profiles</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#how-tag-compares">Comparison</a> •
  <a href="https://github.com/sanskarpan/tag-agent/tree/main/docs/prd">PRDs</a>
</p>

---

TAG is a production-grade AI agent orchestration CLI. It routes tasks across 10+ AI providers, manages autonomous loops and cron schedules, tracks spend with hard budget limits, scans for credential leaks, and ships with 44 built-in capabilities — from background job queues to architect/editor agent splits — all backed by a crash-safe WAL-mode SQLite store.

---

## Install

**Python (recommended):**

```bash
pip install tag-agent
```

**pipx (isolated environment):**

```bash
pipx install tag-agent
```

**npm / pnpm (global):**

```bash
npm install -g tag-agent
# pnpm add -g tag-agent
```

> The npm package is a thin Node launcher. On first run it provisions an isolated Python runtime under `~/.tag/npm-runtime/<version>`. Python **3.11+** must be on your `PATH`.

**From source:**

```bash
git clone https://github.com/sanskarpan/tag-agent
cd tag-agent
pip install -e .
```

Requires **Python 3.11 – 3.14**.

---

## Quick Start

```bash
# 1. Provision runtime and import credentials
tag setup

# 2. Import keys from tools you already use
tag import-claude      # Anthropic
tag import-gemini      # Google
tag import-opencode    # OpenCode / OpenRouter

# 3. Submit your first task
tag submit --prompt "Summarise this repository in 3 bullet points"

# 4. Watch the live dashboard
tag dashboard

# 5. Check health
tag doctor --json
```

---

## Features

### Multi-Provider Routing

Route each profile to a different provider. Switch models per-task without touching config files.

| Provider | Import command | Notes |
|---|---|---|
| **Anthropic (Claude)** | `tag import-claude` | Claude 4 Opus/Sonnet/Haiku |
| **OpenAI / Codex** | `tag import-codex` | GPT-5, o3, Codex |
| **Google Gemini** | `tag import-gemini` | Gemini 2.0 Flash / Pro |
| **OpenRouter** | `tag import-opencode` | 300+ models via one key |
| **Mistral** | `tag import-mistral` | Mistral Large / Codestral |
| **AWS Bedrock** | `tag import-aws` | Claude via Bedrock |
| **Cursor** | `tag import-cursor` | BYOK keys from local SQLite |
| **GitHub Copilot** | `tag import-copilot` | `gh` CLI token |
| **Aider** | `tag import-aider` | `.aider.conf.yml` keys |
| **Continue.dev** | `tag import-continue` | All configured providers |
| **Zed** | `tag import-zed` | Language model settings |
| **SSH remote** | `tag import-ssh` | Run agents on remote hosts |
| **Docker** | `tag import-docker` | Containerised agent execution |
| **Modal** | `tag import-modal` | Serverless agent runs |
| **Daytona** | `tag import-daytona` | Workspace-based execution |

Every import writes only to the target profile's local `.env` — no keys leave the machine.

---

### Autonomous Agent Modes

#### Loop — continuous autonomous runs

```bash
# Start a self-iterating agent loop
tag loop start --goal "Monitor the test suite and fix every failing test" --max-iters 20

# Watch progress
tag loop list --json

# Stop when done
tag loop stop <loop-id>
```

The loop worker runs detached from your terminal, commits fixes, re-runs tests, and iterates until the goal is reached or the iteration cap is hit. Approval modes: `auto` (no intervention) or `human` (pause before each iteration).

#### Cron — scheduled agents

```bash
# Run a daily security scan
tag cron add --name nightly-scan --schedule "0 2 * * *" "tag security scan src/"

# Vixie aliases work too
tag cron add --name hourly-health --schedule "@hourly" "tag doctor"

# List, enable, disable
tag cron list
tag cron disable nightly-scan
```

Cron expressions are validated for both format and field ranges (minute 0–59, hour 0–23, etc.). Vixie aliases (`@reboot`, `@daily`, `@weekly`, `@monthly`, `@hourly`) are accepted.

#### Swarm — fan-out to parallel workers

```bash
# Spread one goal across 4 parallel agents
tag swarm --goal "Review all open PRs and leave a comment on each" --workers 4

# Target a named kanban board
tag swarm --board code-review --goal "Analyse security posture" --workers 6
```

Workers use SHA-256 idempotency keys — safe to retry without creating duplicates.

---

### Background Queue

```bash
# Enqueue jobs with priority (1 = lowest, 10 = highest)
tag queue add --prompt "Generate API docs" --priority 8
tag queue add --prompt "Run regression tests" --priority 5

# With dependency ordering
tag queue-dep add "Generate changelog" --depends-on <upstream-job-id>
tag queue-dep promote   # unlock jobs whose deps are done

# Monitor
tag queue list
tag queue status --job-id <id>
tag queue cancel --job-id <id>
```

The queue worker runs detached, survives terminal close, and respects priority ordering across restarts.

---

### Budget Enforcement

```bash
# Set a hard token cap per profile
tag budget set --profile orchestrator --limit 500000 --period daily

# Check current usage
tag budget check --profile orchestrator --json

# List all budgets
tag budget list --json
```

Agents that exceed their budget receive a `BudgetExceeded` error and halt cleanly. The `--json` flag returns `{"profile": "...", "used": 12345, "limit": 500000, "pct": 2.5, "period": "daily"}`.

---

### Architect / Editor Agent Split

Delegate planning to a high-capability model and execution to a faster, cheaper one:

```bash
# Architect designs the changes; editor implements file by file
tag split plan "Refactor the authentication module to use JWT" \
  --architect claude-opus-4 \
  --editor claude-haiku-4-5

# Monitor progress
tag split list
tag split show <run-id> --json

# Supply a pre-built spec (skip the architect call)
tag split plan "Apply these changes" --spec-json '{"items": [...]}'
```

Each accepted change item is committed separately. Rejected items are logged with the editor's reasoning.

---

### Model Fallback Chains

```bash
# If claude-opus-4 fails (context overflow, error, timeout), fall back to sonnet
tag route-fallback add \
  --primary claude-opus-4 \
  --fallback claude-sonnet-4-6 \
  --condition context_overflow \
  --priority 1

# Show chains for the current profile
tag route-fallback list --json

# Test resolution for a given primary + condition
tag route-fallback resolve --primary claude-opus-4 --condition error
```

Supported conditions: `context_overflow`, `error`, `timeout`, `cost_limit`, `any`.

---

### Secret Scanning

```bash
# Scan the whole repo
tag security scan

# Scan a single file
tag security scan src/tag/controller.py

# Machine-readable output
tag security scan --json

# View past scan history
tag security list --json
```

Detects API keys, tokens, passwords, and high-entropy strings across 40+ patterns. Findings include file path, line number, and pattern name — matched values are never displayed.

---

### Diff-Aware Context Injection

```bash
# Inject current branch diff into next agent run
tag diff-context

# Only staged changes
tag diff-context --staged

# From a GitHub PR
tag diff-context --pr 1234 --repo owner/repo

# Output only (for piping)
tag diff-context --output-only --json
```

The diff context is written to `~/.tag/runtime/context/diff_context.md` and picked up automatically by `tag submit`.

---

### OTel / Observability

```bash
# Export spans to a local collector
tag otel-export enable --endpoint http://localhost:4317

# Export to Honeycomb, Datadog, etc.
tag otel-export configure --endpoint https://api.honeycomb.io \
  --header "x-honeycomb-team=<key>"

# Check status
tag otel-export status --json
```

Every agent run emits GenAI semantic conventions spans: model name, token counts, cost, latency per node, tool calls, and error events.

---

### AgentOps Session Observability

```bash
# Connect to AgentOps
tag agentops configure --api-key <key>

# View recent sessions
tag agentops sessions --json

# Deep-dive a session
tag agentops show <session-id> --json
```

---

### Cache Analytics

```bash
# Show prompt cache hit/miss rates per run
tag cache stats --json

# Clear stale cache entries
tag cache clear --older-than 7d
```

---

### Eval Framework

```bash
# Create an eval suite
tag eval create --name "qa-regression" --profile researcher

# Run a suite
tag eval run <eval-id>

# List results
tag eval list --json
```

Use evals to regression-test prompts and catch model degradation in CI.

---

### Notification Hooks

```bash
# Notify on Slack when any run completes
tag notify add --channel slack \
  --event run.completed \
  --config-json '{"webhook_url": "https://hooks.slack.com/..."}'

# Desktop notification
tag notify add --channel desktop --event run.failed

# Test a hook
tag notify test <hook-id>

# List hooks
tag notify list --json
```

Supported channels: `slack`, `email`, `desktop`, `webhook`. Events: `run.completed`, `run.failed`, `budget.exceeded`.

---

### Persona Management

```bash
# Create a named persona with a system prompt
tag persona add --name "strict-reviewer" \
  --system "You are a senior security engineer. Be concise and critical."

# Activate for a submit
tag submit --persona strict-reviewer --prompt "Review this PR"

# List personas
tag persona list --json
```

---

### DAG / Dependency-Aware Queue

```bash
# Add jobs with explicit dependencies
A=$(tag queue-dep add "Fetch upstream data" --json | jq -r .job_id)
B=$(tag queue-dep add "Process data" --depends-on $A --json | jq -r .job_id)
tag queue-dep add "Generate report" --depends-on $B

# Promote jobs whose dependencies are complete
tag queue-dep promote --json

# Inspect the DAG
tag queue-dep list --json
tag dag show --json
```

---

### Vector Tool Retrieval

```bash
# Index all tools in the current profile
tag tool-index index

# Semantic search for the right tool
tag tool-index search "send a Slack message"

# Status
tag tool-index status --json
```

High-cardinality MCP server catalogs are indexed and searched semantically so only the relevant subset enters the context window.

---

### Workspace Context

```bash
# Index the repo for fast context injection
tag workspace index --max-files 5000

# Show what's indexed
tag workspace status --json

# Clear stale entries
tag workspace clear
```

---

### Profile Marketplace

```bash
# Browse published profiles
tag marketplace list
tag marketplace search "security"

# Download and install
tag marketplace install <profile-name>

# Publish your own
tag marketplace publish --profile coder
```

---

### Sandbox / Code Execution

```bash
# Run agent-generated code in an isolated sandbox
tag sandbox run --code "print('hello')" --language python

# List past sandbox runs
tag sandbox list --json
```

---

## Command Reference

### Orchestration & Setup

| Command | Description |
|---|---|
| `tag setup` | Full first-run: runtime, profiles, credentials |
| `tag doctor` | Health check; `--json` for machine-readable |
| `tag bootstrap` | Re-provision profiles without full setup |
| `tag update` | Update the managed Hermes runtime |
| `tag status` | Current profile and model status |
| `tag dashboard` | Rich live view — active runs, queue depth, health |
| `tag tui` | Full orchestrator TUI |
| `tag serve` | Start the TAG HTTP API server |
| `tag web` | Launch web dashboard |

### Task Submission

| Command | Description |
|---|---|
| `tag submit` | Submit a task (direct or kanban) |
| `tag benchmark` | Run benchmark suite; `--model-ref` to compare |
| `tag runs` | Show benchmark history |
| `tag prompt-size` | Measure prompt token count |
| `tag diff-context` | Inject git diff into next run |

### Autonomous Agents

| Command | Description |
|---|---|
| `tag loop start` | Start an autonomous iteration loop |
| `tag loop list` | Show running loops |
| `tag loop stop` | Stop a loop |
| `tag cron add` | Add a scheduled agent job |
| `tag cron list` | List cron jobs |
| `tag cron enable/disable` | Toggle a cron job |
| `tag cron run` | Trigger a cron job immediately |
| `tag cron daemon` | Start the cron scheduler daemon |
| `tag swarm` | Fan-out to N parallel workers |

### Queue & Scheduling

| Command | Description |
|---|---|
| `tag queue add` | Enqueue a job (priority 1–10) |
| `tag queue list` | Show pending/active jobs |
| `tag queue cancel` | Cancel a job |
| `tag queue status` | Job status and result |
| `tag queue-dep add` | Add job with `--depends-on` |
| `tag queue-dep promote` | Unlock dependency-satisfied jobs |
| `tag queue-dep list` | Inspect DAG job graph |
| `tag dag show` | Visualise the dependency graph |

### Models & Profiles

| Command | Description |
|---|---|
| `tag models` | List available models |
| `tag set-model` | Set active model for a profile |
| `tag assignments` | Show all profile→model mappings |
| `tag openrouter-models` | Search OpenRouter catalog |
| `tag route-fallback add` | Add a model fallback rule |
| `tag route-fallback list` | List fallback chains |
| `tag route-fallback resolve` | Test fallback resolution |

### Credential Import

| Command | Description |
|---|---|
| `tag import-claude` | Anthropic API key |
| `tag import-gemini` | Google Gemini key |
| `tag import-codex` | OpenAI Codex CLI |
| `tag import-opencode` | OpenCode / OpenRouter |
| `tag import-continue` | Continue.dev all providers |
| `tag import-mistral` | Mistral / Vibe CLI |
| `tag import-zed` | Zed editor models |
| `tag import-copilot` | GitHub Copilot token |
| `tag import-aider` | Aider config keys |
| `tag import-aws` | AWS Bedrock credentials |
| `tag import-cursor` | Cursor BYOK keys |
| `tag import-ssh` | Remote execution via SSH |
| `tag import-docker` | Containerised execution |
| `tag import-modal` | Modal serverless |
| `tag import-daytona` | Daytona workspaces |
| `tag import-nous-portal` | Nous Portal API |
| `tag import-supermemory` | Supermemory integration |
| `tag import-honcho` | Honcho sessions |

### Observability

| Command | Description |
|---|---|
| `tag otel-export` | Configure OTel span export |
| `tag agentops` | AgentOps session management |
| `tag trace` | View run traces |
| `tag costs` | Spend analytics |
| `tag cache stats` | Prompt cache hit rates |
| `tag logs` | Stream agent logs |

### Budget & Safety

| Command | Description |
|---|---|
| `tag budget set` | Set token/cost limit |
| `tag budget check` | Check usage vs limit |
| `tag budget list` | All configured budgets |
| `tag security scan` | Detect secrets in files |
| `tag security list` | Past scan results |

### Context & Memory

| Command | Description |
|---|---|
| `tag workspace index` | Index repo for context |
| `tag workspace status` | Indexing status |
| `tag mem list` | List memory entries |
| `tag memory-journal add` | Append to journal |
| `tag memory-journal search` | Full-text search |
| `tag memory-journal list` | Recent entries |

### Integrations & Extensions

| Command | Description |
|---|---|
| `tag mcp` | Pass-through to MCP server |
| `tag mcp-registry` | Browse/install MCP servers |
| `tag plugin install` | Install a TAG plugin |
| `tag plugin list` | List installed plugins |
| `tag tools` | List available tools |
| `tag tool-index` | Semantic tool search |
| `tag hooks` | Manage lifecycle hooks |
| `tag template` | Profile templates |

### Agent Split & Eval

| Command | Description |
|---|---|
| `tag split plan` | Architect→Editor agent split |
| `tag split list` | Ongoing split runs |
| `tag split show` | Inspect a split run |
| `tag eval create` | Create eval suite |
| `tag eval run` | Run evaluations |
| `tag eval list` | Eval history |

### Notifications & Personas

| Command | Description |
|---|---|
| `tag notify add` | Add notification hook |
| `tag notify list` | List hooks |
| `tag notify test` | Send test notification |
| `tag persona add` | Create a named persona |
| `tag persona list` | List personas |

### Pass-through (run inside a profile's managed environment)

```bash
tag chat --profile orchestrator -- --help
tag gateway --profile orchestrator -- start
tag kanban --profile orchestrator -- list
tag sessions --profile orchestrator -- list
tag skills --profile orchestrator -- list
tag memory --profile orchestrator -- status
tag model --profile orchestrator -- list
tag profile -- list

# Full escape hatch
tag hermes --profile orchestrator -- gateway start
```

---

## Profiles

TAG ships five built-in profiles, each with independent model, credential, and routing configuration:

| Profile | Role | Default model |
|---|---|---|
| `orchestrator` | Master — delegates tasks, routes results | `openai-codex/gpt-5.4` |
| `researcher` | Worker — web research and summarisation | `openrouter/deepseek/deepseek-v4-flash` |
| `coder` | Worker — implementation and refactoring | `openrouter/qwen/qwen3-coder` |
| `reviewer` | Worker + verifier — code review and QA | `openrouter/deepseek/deepseek-v4-pro` |
| `codex-runtime-master` | Alternate master for Codex app-server flows | Codex runtime |

Override the model for any profile:

```bash
tag set-model --profile coder --ref openrouter/anthropic/claude-sonnet-4-6
tag set-model --profile orchestrator --ref claude-opus-4
```

---

## Task Routing

| Task type | Workers | Verifier | Execution mode |
|---|---|---|---|
| `research` | researcher | reviewer | Kanban |
| `implementation` | coder | reviewer | Kanban |
| `review` | reviewer | reviewer | Direct |
| `mixed` | researcher + coder | reviewer | Kanban |

---

## Architecture

```
tag CLI
├── Management plane  (SQLite WAL — no API key needed)
│   ├── loop.py        autonomous iteration loop
│   ├── cron.py        scheduled cron agent jobs
│   ├── kanban.py      native task management
│   ├── queue_worker   priority background jobs
│   ├── dag.py         dependency-aware DAG queue
│   ├── budget.py      token/cost enforcement
│   ├── security.py    secret scanning
│   ├── diff_context   git diff injection
│   ├── split_agent    architect/editor split
│   ├── otel_semconv   OpenTelemetry spans
│   ├── agentops       session observability
│   ├── notifications  webhook/Slack/email hooks
│   └── dashboard      Rich live TUI
└── Execution plane   (Hermes gateway — API key required)
    ├── swarm          fan-out topology
    ├── submit         direct / kanban dispatch
    └── tui            full terminal UI
```

State lives entirely in `~/.tag/runtime/tag.sqlite3` (WAL mode, 40+ tables). The split means queue, loop, cron, dashboard, doctor, split, eval, budget, security, and all import commands work **offline and without an active API key**.

```bash
export TAG_HOME=/custom/path   # override root
```

```
~/.tag/
  config/tag.yaml
  config/benchmark-suite.yaml
  managed/hermes-agent-upstream/
  runtime/
    tag.sqlite3          # WAL-mode state store
    context/
      diff_context.md    # last injected diff
    home/                # Hermes runtime home
```

---

## How TAG Compares

| Feature | TAG | Claude Code | Aider | AutoGen | CrewAI |
|---|---|---|---|---|---|
| **CLI-first** | ✓ | ✓ | ✓ | — | — |
| **Any provider** | ✓ (15+ imports) | Anthropic only | ✓ | ✓ | ✓ |
| **Background queue** | ✓ priority + DAG | — | — | — | — |
| **Cron scheduling** | ✓ | — | — | — | — |
| **Autonomous loop** | ✓ | via subagents | — | ✓ | ✓ |
| **Budget enforcement** | ✓ hard limit | spend tracking | — | — | — |
| **Secret scanning** | ✓ built-in | — | — | — | — |
| **OTel tracing** | ✓ | — | — | — | — |
| **Architect/editor split** | ✓ | — | ✓ | — | — |
| **Model fallback chains** | ✓ | — | — | — | — |
| **Diff-aware context** | ✓ | — | ✓ (repo-map) | — | — |
| **Notification hooks** | ✓ Slack/email/desktop | — | — | — | — |
| **Eval framework** | ✓ | — | — | — | — |
| **Persona management** | ✓ | CLAUDE.md | — | — | ✓ roles |
| **Profile marketplace** | ✓ | — | — | — | — |
| **WAL-mode persistence** | ✓ | — | — | — | — |
| **MCP registry** | ✓ | ✓ | — | — | — |
| **AgentOps integration** | ✓ | — | — | — | — |
| **Vector tool retrieval** | ✓ | deferred loading | — | — | — |
| **No API key for mgmt** | ✓ | — | — | — | — |

---

## Configuration

All configuration lives in `~/.tag/config/tag.yaml`. The most common overrides:

```yaml
defaults:
  master_profile: orchestrator

profiles:
  coder:
    model:
      provider: openrouter
      ref: qwen/qwen3-coder

security:
  secret_scan_on_submit: true

queue:
  max_workers: 4
  default_priority: 5
```

---

## Requirements

- Python **3.11 – 3.14**
- `npm` — required for the full TUI build (not needed for submit / queue / loop / dashboard)
- `git` — recommended; required for `tag diff-context` and `tag update`

---

## Contributing

```bash
git clone https://github.com/sanskarpan/tag-agent
cd tag-agent
pip install -e ".[dev]"
pytest tests/ -x -q --ignore=tests/hermes_cli
```

Design decisions and feature specs live in [`docs/prd/`](docs/prd/) — 44 PRDs covering every subsystem. Open an issue before implementing a significant feature.

---

## Changelog

See [GitHub Releases](https://github.com/sanskarpan/tag-agent/releases) for the full history.

**v0.6.4** — Adversarial QA complete: 13 bugs fixed across DB resilience, cron validation, `--json` coverage, budget check, queue-dep list, and more.

**v0.3.0** — Added imports for opencode, Zed, Copilot, Aider, AWS, and Cursor.

---

## License

MIT — see [LICENSE](https://github.com/sanskarpan/tag-agent/blob/main/LICENSE).

---

<p align="center">
  Made with care. Built for the terminal.
</p>

