talaria-cli 0.2.8

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 v0.2.8 (pip install talaria-cli && talaria setup) and use it to delegate tasks through my Claude subscription instead of API billing. For future releases, run talaria update. 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), Talaria routes delegated work through Claude Code print mode. That usually means the work counts against your Claude subscription's included usage first, not your own API key. But it is not a verified guarantee of zero paid overage forever - once you hit included limits, Claude's optional extra usage can bill separately if enabled on your account.

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.

Important billing reality check:

• if Claude Code is authenticated with your Claude account (claude auth login / authMethod: claude.ai), usage goes against your included Claude plan limits first
• if ANTHROPIC_API_KEY is set, Claude Code uses that API key instead and you get direct API charges
• if you exhaust included plan limits and have extra usage enabled, Claude Code usage can incur extra paid usage at standard rates
• Talaria does not provide a verified magic bypass for extra usage; it just routes work through Claude Code instead of your own API integration

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

# Let Claude choose adaptively
talaria run "Review this migration strategy" --effort adaptive

# Ask for xhigh - falls back to max until your Claude CLI exposes xhigh
talaria run "Stress-test this architecture" --effort xhigh

# Set defaults
talaria config set default_model opus
talaria config set default_effort medium

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

adaptive and auto are aliases - Talaria omits the flag so Claude chooses automatically. xhigh passes through when the installed Claude CLI supports it and falls back to max on older CLIs instead of exploding like a clown.

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 Claude Code instead. On a Pro/Max/Team subscription that means usage hits your included Claude limits first. If you have ANTHROPIC_API_KEY set, or if you blow past included limits with extra usage enabled, you can still see paid usage.

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

Latest stable release: v0.2.8

pip install talaria-cli
talaria setup

# Future upgrades
# Pull the newest Talaria release into the current Python environment
# and refresh setup in one shot
talaria update

talaria setup installs the agent skill, creates a conventions file, and verifies everything works. talaria update upgrades the package in the current Python environment, refreshes setup, and is the intended path for future Talaria releases.

Quick Start

If you already installed Talaria before v0.2.8, just run talaria update instead of reinstalling from scratch.

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

Billing behavior

Talaria uses Claude Code print mode, not the Anthropic SDK. What that means in practice:

• Best case: authenticated with claude.ai, under your included Pro/Max/Team limits, extra usage disabled - no separate paid overage
• Still safe but not free: authenticated with claude.ai, extra usage enabled, or you're past included limits - usage can become paid extra usage
• Definitely paid: ANTHROPIC_API_KEY is set and Claude Code authenticates with the API key instead of your subscription

If zero overage is non-negotiable, disable extra usage in Claude Settings > Usage and stay within included limits. The tradeoff is simple: when you hit the cap, Claude Code stops until the limit resets instead of charging through it.

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 because Claude Code print-mode usage is otherwise pretty opaque. Talaria labels these numbers as Claude-reported usage on purpose - they are useful for local guardrails and trend tracking, but not proof of separate API billing by themselves.

talaria usage today
talaria usage week
talaria logs failures

Scheduled Jobs (Cron)

Run recurring tasks through Claude Code account auth instead of your own API integration. 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