hum

Small agents that keep running.

An agent runs on a schedule, persists notes between sessions, and accepts messages over one or more channels. You define it in YAML and manage it with the hum CLI.

Install

pip install hum

You also need a running ACP-compatible agent binary on your PATH. For Claude:

pip install claude-agent-acp
export ANTHROPIC_API_KEY=sk-...

Define an agent

Create a YAML file:

# assistant.yaml
name: my-assistant
description: A focused personal assistant
system: You are a focused personal assistant. Keep responses short and useful.
backend:
  command: [claude-agent-acp]
channels:
  - type: http
    port: 8000
heartbeat:
  every: 10m
  prompt: |
    Your current notes:
    {notes}

    Do a brief check-in. Note anything worth remembering.
memory: ./notes.md

Fields

Field	Required	Description
name	yes	Unique agent name
system	yes	System prompt
backend.command	yes	Command to launch the ACP agent process
channels	yes*	List of channel configs (see below). At least one required
heartbeat.every	no	How often the agent wakes up (s, m, h, d)
heartbeat.prompt	no	Prompt sent on each heartbeat. {notes} is replaced with current notes
memory	no	Path to the notes file (default: ~/.hum/agents/<name>/notes.md)
description	no	Human-readable description

*The legacy port field is still accepted as a shorthand for channels: [{type: http, port: <n>}].

Channels

Channels define how the agent receives messages. Multiple channels can run concurrently.

HTTP channel — listens for POST /message requests:

channels:
  - type: http
    port: 8000

stdin channel — reads lines from stdin, prints replies to stdout:

channels:
  - type: stdin

Both at once:

channels:
  - type: http
    port: 8000
  - type: stdin

Manage agents

# Register
hum new --file assistant.yaml

# List registered agents
hum list

# Run
hum run my-assistant

# Remove
hum remove my-assistant

Send messages

While the agent is running, send messages via HTTP:

curl -X POST http://localhost:8000/message \
  -H 'Content-Type: application/json' \
  -d '{"message": "What should I focus on today?"}'

Response:

{"response": "Based on your notes, you mentioned the report is due Friday..."}

How it works

Heartbeat — on each tick the agent receives the heartbeat prompt (with {notes} filled in) and runs it through the LLM. Use this for background work: summarising, checking in, updating notes.

Messages — incoming messages (HTTP or stdin) are sent to the LLM with the same system prompt. For HTTP, the response is returned synchronously as JSON. For stdin, the reply is printed to stdout.

Notes — a persistent markdown file the agent can read and update between beats via the update_notes tool. The current content is injected into heartbeat prompts via {notes}.

Concurrency — heartbeat and HTTP handling run concurrently in the same process. The agent does background work on schedule and still responds to messages.

Backend — agents run as ACP (Agent Client Protocol) subprocesses. hum spawns the process, holds a session open for the agent's lifetime, and routes prompts through it.

Examples

See the examples/ directory:

File	Description
basic.yaml	Personal assistant, checks in every 10 minutes
journal.yaml	Journaling companion, prompts reflection twice a day
standup.yaml	Work standup bot, daily done/next/blockers log
habit-tracker.yaml	Habit tracker with streak awareness
research-digest.yaml	Research synthesis assistant, surfaces gaps every 6 hours
focus-timer.yaml	Pomodoro coach, checks in every 25 minutes