Zeta runs agents that stay with your work.

Define each agent in Markdown. Zeta wakes it when relevant events occur. Agents can use tools, pass work to other agents, and retain a durable record of each action.

Use Zeta to give an agent an ongoing responsibility:

• Read and sort each new file in an inbox.
• Prepare a weekly report on a schedule.
• Respond to a Slack message.
• Hand a completed task to another agent.

Your first agent can stay on top of an inbox. You give it the responsibility once. When a file arrives, it writes a summary where you can use it.

Zeta needs Python 3.11+ and Codex. Run codex login once before you start.

Install Zeta:

uv tool install zeta-os

Create the default inbox-summarizer project:

zeta new ~/zeta-demo
cd ~/zeta-demo

zeta new creates the agent, its inbox, its summary folder, and its filesystem connector. It also excludes runtime state from Git.

To use a different model, see Model Profiles.

Start Zeta in one terminal:

zeta serve

Create a file in a second terminal:

echo "Buy milk. Send the release notes before Friday." \
  > ~/zeta-demo/inbox/todo.txt

Create the file after Zeta starts. The filesystem connector ignores files that exist before its first poll.

Open the result:

cat ~/zeta-demo/summaries/todo.txt.md

For this file, the summary can be:

The file lists two tasks: buy milk and send release notes before Friday.

Zeta detects the file, starts the agent, and writes the summary. You did not need to ask it again.

Want to inspect the work behind the result?

zeta traces log --session agent/inbox-summarizer

An agent is one Markdown file in agents/.

Its frontmatter declares the events it accepts, the tools it may use, and the events it may publish. Its body gives the agent instructions.

---
name: Release Digest
description: Prepares the weekly release digest.
schedules:
  - cron: "0 9 * * 1"
    timezone: Europe/Paris
    catchup: latest
publishes:
  - release.summary.ready
tools:
  - bash
---
Summarize pull requests merged during the last week.

Write release notes for the team. Use `publish_event` to publish them as
`release.summary.ready`.

A schedule creates an event for the agent. A published event can start another agent.

Events connect agents.

One agent can prepare release notes. Another agent can publish them. Each handoff has a named event and a validated payload.

schedule
  -> release-digest
  -> release.summary.ready
  -> announcer
  -> Slack

Put project event schemas in agents/events/.

agents/
  connectors.yaml
  release-digest.md
  announcer.md
  events/
    release.summary.ready.json
  skills/
    release-notes.md

Use zeta run to process pending work and exit.

zeta run

Use zeta serve for continuous work, schedules, and connector ingress.

zeta serve

Zeta includes file and shell tools:

• read
• grep
• edit
• write
• bash

Agents only receive tools that their Markdown declaration lists.

Shared skills live in agents/skills/. A skill is a Markdown procedure that multiple agents can use.

---
name: Support Triage
description: Sorts support requests.
skills:
  - support-policy
tools:
  - read
  - write
---
Apply the support policy to this request:

{{ event.payload.message }}

Zeta stores events, queue state, model requests, tool calls, and agent results. Runtime state lives in the project .zeta/ directory.

Use the CLI to inspect work:

zeta ps
zeta events list
zeta queue list
zeta attempts list
zeta traces log --all-sessions

Inspect the exact prompt for an agent response:

zeta traces show PROMPT_ID --session agent/inbox-summarizer

Replay that prompt with another model profile:

zeta traces replay PROMPT_ID \
  --session agent/inbox-summarizer \
  --model codex \
  --diff

Replay is not the reason to use Zeta. It is how you can trust an ambient agent after it acts.

Concepts covers agent files, events, schemas, connectors, model profiles, schedules, runtime state, and the CLI.

Trace replay demo shows prompt inspection and model comparison.

uv sync --group dev
uv run pre-commit run --all-files
uv run pytest

Apache-2.0. See LICENSE.