Metadata-Version: 2.4
Name: talaria-cli
Version: 0.2.8
Summary: Hermes' winged sandals - route AI agent tasks through session-billed CLI backends instead of per-token API calls.
Project-URL: Homepage, https://github.com/Zer0Wav3s/talaria-cli
Project-URL: Issues, https://github.com/Zer0Wav3s/talaria-cli/issues
Author: ZeroWaves
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: packaging>=24.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

![talaria banner](assets/banner.png)

<div align="center">

# 🪽 Talaria CLI

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

[![PyPI](https://img.shields.io/pypi/v/talaria-cli?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9&cacheSeconds=300)](https://pypi.org/project/talaria-cli/)
[![License](https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge)](https://github.com/Zer0Wav3s/talaria-cli/blob/main/LICENSE)

</div>

---

### → For agents: read [`llms.txt`](https://raw.githubusercontent.com/Zer0Wav3s/talaria-cli/main/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

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

```bash
# 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](https://www.anthropic.com/legal/consumer-terms) (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`**

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

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

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

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

```python
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.

```bash
talaria config set conventions_file ~/my-conventions.md
```

### Post-Dispatch Verification
Run a command after dispatch to prove the work is correct.

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

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

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

```bash
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 * * *`).

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

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

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