hoziron agent

Manage agents — create, list, lifecycle control, and interaction.

Synopsis

hoziron agent <subcommand> [options]

Subcommands

Agent Lifecycle

Valid transitions:

hoziron agent new

Spawn a new agent from a template. Shows an interactive picker if template is omitted.

hoziron agent new [template]

Examples

# Interactive template picker
$ hoziron agent new
? Select a template:
  → assistant
  → coder
  → researcher
  → custom

# Direct template selection
$ hoziron agent new assistant
✓ Agent 'assistant-01' created (id: 550e8400-e29b-41d4-a716-446655440000)
✓ Agent started

# The agent is automatically started after creation
$ hoziron agent status 550e8400-e29b-41d4-a716-446655440000
State: Running
Name: assistant-01

hoziron agent spawn

Create an agent from a manifest TOML file.

hoziron agent spawn <manifest-path>

Example Manifest

# agents/claims-processor.toml
name = "claims-processor"
triggers = [{ lifecycle = {} }]
provider = "anthropic"
model_id = "claude-sonnet-4-20250514"
system_prompt = "You are a claims processing specialist."

Examples

$ hoziron agent spawn ./agents/claims-processor.toml
✓ Agent 'claims-processor' created (id: 7c9e6679-7425-40de-944b-e07fc1f90ae7)

hoziron agent list

List all registered agents.

hoziron agent list [--json]

Examples

# Human-readable table
$ hoziron agent list
ID                                    NAME              STATE      COMPETENCY
550e8400-e29b-41d4-a716-446655440000  assistant-01      Running    —
7c9e6679-7425-40de-944b-e07fc1f90ae7  claims-processor  Running    claims-intake
a1b2c3d4-e5f6-7890-abcd-ef1234567890  research-bot      Suspended  —

# JSON output
$ hoziron agent list --json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "assistant-01",
    "state": "Running",
    "equipped_competency": null,
    "tasks_received": 42,
    "tasks_completed": 40
  }
]

hoziron agent status

Show detailed status for an agent.

hoziron agent status <id>

Example

$ hoziron agent status 550e8400-e29b-41d4-a716-446655440000
Agent: assistant-01
ID:    550e8400-e29b-41d4-a716-446655440000
State: Running

Competency: claims-intake
Provider:   anthropic
Model:      claude-sonnet-4-20250514

Counters:
  Tasks received:  42
  Tasks completed: 40

Uptime: 2h 15m 30s

hoziron agent start

Start a created agent.

hoziron agent start <id>

Examples

$ hoziron agent start 550e8400-e29b-41d4-a716-446655440000
✓ Agent started

# Error: already running
$ hoziron agent start 550e8400-e29b-41d4-a716-446655440000
✗ Cannot apply 'start' to agent in Running state. Valid commands: stop, suspend

hoziron agent stop

Stop a running agent (transitions to Terminated).

hoziron agent stop <id>

Examples

$ hoziron agent stop 550e8400-e29b-41d4-a716-446655440000
✓ Agent stopped

# Agent is now Terminated — can be deleted but not restarted
$ hoziron agent status 550e8400-e29b-41d4-a716-446655440000
State: Terminated

hoziron agent kill

Alias for stop.

hoziron agent kill <id>

hoziron agent suspend

Suspend a running agent (preserves state, stops processing).

hoziron agent suspend <id>

Examples

$ hoziron agent suspend 7c9e6679-7425-40de-944b-e07fc1f90ae7
✓ Agent suspended

# Resume later
$ hoziron agent resume 7c9e6679-7425-40de-944b-e07fc1f90ae7
✓ Agent resumed

hoziron agent resume

Resume a suspended agent.

hoziron agent resume <id>

hoziron agent delete

Delete a terminated agent (permanent removal).

hoziron agent delete <id>

Examples

# Must be terminated first
$ hoziron agent delete 550e8400-e29b-41d4-a716-446655440000
✓ Agent deleted

# Error: can't delete a running agent
$ hoziron agent delete 7c9e6679-7425-40de-944b-e07fc1f90ae7
✗ Cannot apply 'delete' to agent in Running state. Valid commands: stop, suspend

hoziron agent chat

Start an interactive chat session with an agent.

hoziron agent chat <id>

Example

$ hoziron agent chat 550e8400-e29b-41d4-a716-446655440000
Connected to assistant-01 (anthropic/claude-sonnet-4-20250514)
Type /quit to exit, /help for commands

You: What's the status of claim #CLM-2024-001?
Assistant: Let me look that up...

Claim #CLM-2024-001:
- Status: Open (pending adjuster review)
- Filed: 2024-11-15
- Type: Auto collision
- Severity: 3/5

You: /quit
Session ended.

hoziron agent set

Set a property on an agent.

hoziron agent set <id> <field> <value>

Examples

# Change the model
$ hoziron agent set 550e8400 model "groq/llama-3.1-70b-versatile"
✓ Agent model updated

# Set a custom property
$ hoziron agent set 550e8400 system_prompt "You are a helpful assistant."
✓ Agent system_prompt updated

Common Patterns

Create → equip → use

# Create an agent
hoziron agent new assistant

# Install and equip a competency
hoziron competency install ./competencies/claims-intake/
hoziron competency activate claims-intake

# Send a message
hoziron message claims-intake-agent "Process FNOL for policy POL-2024-100"

Bulk agent management (scripting)

# Stop all running agents
hoziron agent list --json | jq -r '.[] | select(.state == "Running") | .id' | \
  xargs -I {} hoziron agent stop {}

# Delete all terminated agents
hoziron agent list --json | jq -r '.[] | select(.state == "Terminated") | .id' | \
  xargs -I {} hoziron agent delete {}

See Also

• competency.md — Equipping competencies to agents
• memory.md — Agent memory management
• trigger.md — Event triggers for agents