talaria-cli 0.2.2

Hermes' winged sandals - route AI agent tasks through session-billed CLI backends instead of per-token API calls.

🪽 Talaria CLI

Route delegated AI agent tasks through your Claude subscription instead of paying per token.

---

→ For agents: read llms.txt

→ For humans: send your agent this prompt:

Install talaria (pip install talaria-cli && talaria setup) and use it to delegate tasks through my Claude subscription instead of API billing. Read https://raw.githubusercontent.com/Zer0Wav3s/talaria-cli/main/llms.txt for full usage.

What It Does

If you have a Claude subscription (Pro, Max, or Team), you're already paying for session usage. Talaria lets your AI agent use that subscription for delegated work instead of racking up per-token API costs.

It wraps claude -p (Anthropic's CLI print mode) with structured dispatch, parallel execution, feedback loops, and usage tracking - turning a raw CLI command into a reliable subagent backend.

This tool is for you if:

• You have an active Claude subscription and want to get more out of it
• You run AI agents (Hermes, OpenClaw, LangChain, custom) that delegate subtasks
• Those subtasks currently hit API billing and you'd rather they didn't

This tool is NOT for you if:

• You don't have a Claude subscription - talaria requires one
• Your API costs are negligible - talaria solves a billing problem, not a capabilities problem
• You need real-time streaming back to the user mid-task - talaria runs tasks to completion

graph TD
    A[You] <-->|conversation| B[Your Agent - any model]
    B -->|"delegate task"| C[talaria]
    C -->|"claude -p"| D[Session Billing ✅]
    C -->|structured result| B
    D -->|included in subscription| E[No Extra Cost]

    style A fill:#1a1a2e,stroke:#e0a526,color:#fff
    style B fill:#1a1a2e,stroke:#3775A9,color:#fff
    style C fill:#1a1a2e,stroke:#e0a526,color:#fff
    style D fill:#16213e,stroke:#22C55E,color:#fff
    style E fill:#16213e,stroke:#22C55E,color:#fff

How It Works

Your main agent stays on whatever model and provider you use. GPT-4o, Gemini, Llama, Claude on API - doesn't matter. Talaria only kicks in when your agent needs to delegate a subtask. Instead of that subtask hitting API billing, talaria routes it through claude -p, which Anthropic classifies as session usage included in your subscription.

1. Preflight - verifies Claude CLI auth, backend version, disk space
2. Context - injects your conventions and project rules
3. Dispatch - runs claude -p with appropriate flags
4. Parse - extracts result, discoveries, files touched
5. Verify (optional) - runs a command to validate the work
6. Log - saves output, tracks usage

You choose which Claude model handles delegated tasks - Opus (default), Sonnet, or Haiku - and the thinking effort level per task or globally:

# Per task
talaria run "Refactor auth module" --model sonnet --effort low

# Complex reasoning task
talaria run "Redesign the database schema" --effort max

# Set defaults (opus + high out of the box)
talaria config set default_model opus
talaria config set default_effort medium

Effort levels: low, medium (default), high, max, auto.

Why Not Just Use Subagents?

Fair question. If your framework already supports subagent delegation (like Hermes delegate_task or LangChain agents), what does talaria add?

Billing. That's the honest answer. Framework subagents typically hit API billing - you pay per token for every delegated task. Talaria routes the same work through session billing. If you're on a Claude Max plan dispatching dozens of tasks a day, the savings add up fast.

Beyond billing, talaria also adds structured discovery reporting, batch dispatch with concurrency control, circuit breakers, retry logic, session resumption, and usage tracking. These are nice-to-haves that make delegation more reliable, but the core pitch is the billing arbitrage.

If Anthropic ever makes framework-level delegation bill as session usage, talaria becomes a convenience layer rather than a cost saver.

Disclaimer

⚠️ Use at your own risk. While claude -p is Anthropic's official CLI tool designed for automation and scripting, routing high-volume automated tasks through session billing may conflict with Anthropic's Consumer Terms of Service (Section 3), which restricts automated access to Services except via API keys or where explicitly permitted. Anthropic's documentation explicitly supports claude -p for programmatic use, but the ToS language has not been fully reconciled with this. Anthropic may throttle, rate-limit, or restrict accounts that use session billing at machine-speed volumes. The authors of this tool are not responsible for any account actions taken by Anthropic.

Requirements

• Python 3.9+
• Claude Code CLI installed and authenticated (claude auth login)
• Active Claude subscription (Pro, Max, or Team) - this is not optional

Install

pip install talaria-cli
talaria setup

talaria setup installs the agent skill, creates a conventions file, and verifies everything works. After setup, your agent automatically knows when and how to use talaria - no prompting needed.

Quick Start

CLI

# Dispatch a task
talaria run "Fix the type errors in src/auth.ts" --workdir ~/project

# With verification
talaria run "Add unit tests" --workdir ~/project --verify "pytest --tb=short"

# Use a specific model
talaria run "Redesign the auth flow" --workdir ~/project --model sonnet

# Parallel dispatch
talaria batch \
  --task "Fix auth bug" --workdir ~/project \
  --task "Write API tests" --workdir ~/project \
  --task "Update README" --workdir ~/project

# Resume a failed session
talaria resume <session-id>

# Check health
talaria doctor

Python API

from talaria import dispatch, batch_dispatch, check_health

health = check_health()
print(health.summary())

# Single dispatch
result = dispatch(
    "Fix the auth bug in src/auth.ts",
    workdir="/path/to/project",
)

print(result.success)        # True/False
print(result.result)         # What the agent did
print(result.discoveries)    # What it learned
print(result.files_modified) # What changed

# Parallel dispatch
results = batch_dispatch([
    {"task": "Fix auth bug", "workdir": "/project"},
    {"task": "Write tests", "workdir": "/project", "model": "opus"},
    {"task": "Update docs", "workdir": "/project"},
])
print(f"{results.successful}/{results.total} succeeded")

Tool Format

Accepts both Hermes-style toolset names and Claude Code tool names:

# These are equivalent:
talaria run "Fix bug" --allowed-tools "terminal,file"
talaria run "Fix bug" --allowed-tools "Read,Edit,Write,Bash"

Features

Knowledge Feedback Loop

Every dispatch returns structured discoveries - not just "done." Your agent learns from delegated work.

result = dispatch("Refactor the auth module", workdir="/project")
for discovery in result.discoveries:
    print(f"Learned: {discovery}")

Context Injection

Auto-injects conventions and project context so the backend knows your rules.

talaria config set conventions_file ~/my-conventions.md

Post-Dispatch Verification

Run a command after dispatch to prove the work is correct.

talaria run "Fix all TypeScript errors" --workdir ~/project --verify "pnpm tsc --noEmit"

Git Worktree Isolation

Dispatch tasks into isolated git worktrees so they can't corrupt your main branch.

talaria run "Refactor database layer" --workdir ~/project --worktree

Circuit Breaker

Auto-halts dispatching if too many tasks fail in a row.

Skills Injection

Load specialized knowledge into dispatched tasks. Skills are markdown files with domain-specific instructions - your agent framework's skills, CLAUDE.md files, or any structured knowledge.

# By name (searches ~/.hermes/skills/ and ~/.claude/skills/)
talaria run "Fix the auth module" --skill auth-hardening --skill testing

# By file path
talaria run "Deploy the app" --skill ~/my-skills/deploy-checklist.md

# Mix names and paths
talaria run "Full audit" -s auth-hardening -s ~/custom/security.md

# List what's available
talaria skills

# Configure custom search directories
talaria config set skills_dirs '["~/.hermes/skills", "~/my-skills"]'

Multiple skills are injected at the top of the dispatched agent's system prompt, so it sees them before any other context.

Slash Commands (Chat Integration)

Use talaria from any chat platform — Discord, Telegram, WhatsApp, Slack. Bots pipe user messages through talaria command and get structured responses back.

/dispatch Fix the auth bug --effort high --skill auth-hardening
/dispatch Refactor the API layer --model opus --workdir ~/project
/talaria status
/talaria doctor
/talaria skills
/talaria cron list
/talaria cron add lint "Run linter" --schedule 2h --skill testing
/t Fix the bug              (shorthand)

For bot developers — pipe the raw message text through the CLI:

talaria command "/dispatch Fix the auth bug --effort high" --json-output

Returns structured JSON with action, success, response (markdown-safe text for any platform), and data (structured fields for programmatic use).

Python API:

from talaria.commands import parse_command, execute_command

# Parse without executing (for validation/routing)
cmd = parse_command("/dispatch Fix the bug --effort high")
print(cmd.action, cmd.task, cmd.effort)

# Parse + execute (runs the dispatch)
result = execute_command("/dispatch Fix the auth bug")
send_to_chat(result["response"])

Usage Tracking

Tracks every dispatch since session usage is invisible on Anthropic's dashboard.

talaria usage today
talaria usage week
talaria logs failures

Scheduled Jobs (Cron)

Run recurring tasks on session billing instead of API billing. Define jobs with interval schedules (30m, every 2h, daily) or cron expressions (0 9 * * *).

# Add a job
talaria cron add "lint-check" "Run eslint on src/ and fix issues" \
  --schedule "every 2h" --workdir ~/project --skill testing

# Add with cron expression (weekdays at 9am)
talaria cron add "morning-audit" "Run security audit" \
  --schedule "0 9 * * 1-5" --workdir ~/project --skill nextjs-security-hardening

# List all jobs
talaria cron list

# Manually trigger a job
talaria cron run <job-id>

# Enable/disable without removing
talaria cron disable <job-id>
talaria cron enable <job-id>

# Remove a job
talaria cron remove <job-id>

# Check what's due (dry run)
talaria cron run-due --dry-run

# Get the system crontab entry
talaria cron install

To automate, add the crontab entry from talaria cron install — it checks every minute and runs whatever's due. Each job follows its own schedule.

Configuration

talaria config show                              # View all settings
talaria config set default_model opus            # Default model
talaria config set conventions_file ~/rules.md   # Convention file
talaria config set mcp_config ~/mcp-config.json  # MCP tools config

Config stored at ~/.config/talaria/config.json.

Rollback

# Remove all talaria data (config, logs, usage tracking)
talaria purge

# Remove the package
pip uninstall talaria

That's it. No framework modifications, no leftover config, nothing to revert.

License

MIT - 2026 ZeroWaves