Orchestrate AI agents from your terminal — multi-source credential import, swarm topology, background queue, live dashboard

These details have not been verified by PyPI

Project description

TAG

TAG — Terminal Agent Gateway

Orchestrate AI agents from your terminal.
Any model. Any provider. One CLI.

Install • Quick Start • Features • Commands • Profiles • Architecture • Comparison • PRDs

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):

pip install tag-agent

pipx (isolated environment):

pipx install tag-agent

npm / pnpm (global):

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:

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

Requires Python 3.11 – 3.14.

Quick Start

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

Eval Framework

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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:

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.

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:

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

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/ — 44 PRDs covering every subsystem. Open an issue before implementing a significant feature.

Changelog

See GitHub 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.

Made with care. Built for the terminal.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.8.2

Jul 1, 2026

0.8.1

Jul 1, 2026

0.8.0

Jun 30, 2026

This version

0.7.1

Jun 22, 2026

0.7.0

Jun 22, 2026

0.6.4

Jun 16, 2026

0.6.3

Jun 16, 2026

0.6.2

Jun 15, 2026

0.6.1

Jun 15, 2026

0.6.0

Jun 15, 2026

0.5.0

Jun 12, 2026

0.4.0

Jun 12, 2026

0.3.0

Jun 11, 2026

0.2.0

Jun 11, 2026

0.1.0

Jun 10, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tag_agent-0.7.1.tar.gz (55.0 MB view details)

Uploaded Jun 22, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tag_agent-0.7.1-py3-none-any.whl (55.0 MB view details)

Uploaded Jun 22, 2026 Python 3

File details

Details for the file tag_agent-0.7.1.tar.gz.

File metadata

Download URL: tag_agent-0.7.1.tar.gz
Upload date: Jun 22, 2026
Size: 55.0 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for tag_agent-0.7.1.tar.gz
Algorithm	Hash digest
SHA256	`1096105e8795440c678182e52be9eab7e2c1460d6ded0f1cd859a0986d9eb3ef`
MD5	`620403bbd944c31f7eb3aa1477083f6a`
BLAKE2b-256	`b5876d1f3cc05137bc17df4b7565b3d334dd464220fc892d2d4ad474043ee06d`

See more details on using hashes here.

File details

Details for the file tag_agent-0.7.1-py3-none-any.whl.

File metadata

Download URL: tag_agent-0.7.1-py3-none-any.whl
Upload date: Jun 22, 2026
Size: 55.0 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for tag_agent-0.7.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5baf9949a7ebe81f82a03c58a5ff801fbb31008ace202da451409a7310fd2a8a`
MD5	`8e0108cfc959ded782b3f6b744e79adc`
BLAKE2b-256	`3315522e99e506602429e10fb43dbcff3d1cac8ced09f4feb8b17b6922bb86b1`

See more details on using hashes here.

tag-agent 0.7.1

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

TAG — Terminal Agent Gateway

Install

Quick Start

Features

Multi-Provider Routing

Autonomous Agent Modes

Loop — continuous autonomous runs

Cron — scheduled agents

Swarm — fan-out to parallel workers

Background Queue

Budget Enforcement

Architect / Editor Agent Split

Model Fallback Chains

Secret Scanning

Diff-Aware Context Injection

OTel / Observability

AgentOps Session Observability

Cache Analytics

Eval Framework

Notification Hooks

Persona Management

DAG / Dependency-Aware Queue

Vector Tool Retrieval

Workspace Context

Profile Marketplace

Sandbox / Code Execution

Command Reference

Orchestration & Setup

Task Submission

Autonomous Agents

Queue & Scheduling

Models & Profiles

Credential Import

Observability

Budget & Safety

Context & Memory

Integrations & Extensions

Agent Split & Eval

Notifications & Personas

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

Profiles

Task Routing

Architecture

How TAG Compares

Configuration

Requirements

Contributing

Changelog

License

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes