Metadata-Version: 2.4
Name: talaria-cli
Version: 0.2.2
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: rich>=13.0
Description-Content-Type: text/markdown

![talaria banner](https://raw.githubusercontent.com/Zer0Wav3s/talaria-cli/main/assets/banner.png)

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

---

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

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

# 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](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

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

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

### 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 since session usage is invisible on Anthropic's dashboard.

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

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