agent-factory

Turn "I keep meaning to automate this" into a scheduled Claude Code agent in minutes, not an afternoon.

This is a small, opinionated factory for scheduled Claude Code automations, built on top of Orca (the desktop scheduler that actually fires the runs). It gives you:

• A template for agent repos: manifest, prompt, permissions, an optional bash allowlist so a "deterministic pipeline" agent can't improvise outside its script.
• A tool catalog (catalog/tools.toml) that tells you, per tool, whether it's safe to run unattended — and refuses to let you schedule the ones that aren't (browser extensions, claude.ai connectors — anything that needs an interactive session).
• A scaffolder (/new-agent in Claude Code, or runner/scaffold_agent.py from the shell) that stamps a new agent repo, walks you through wiring up MCPs/CLIs/credentials, and registers it.
• A sync script (runner/sync_orca.py) that reconciles your agents' manifests into Orca's schedule — the manifest is the source of truth, never the Orca UI.
• A run contract: every agent writes out/result.json before it exits. Nothing downstream trusts exit codes or model prose — only that file.

No telemetry, no hosted service, no account. It's a git repo and two Python scripts; everything runs on your own machine(s).

Quickstart

Requirements: Claude Code and Orca installed, claude authenticated (subscription session or ANTHROPIC_API_KEY), Python ≥3.11 (stdlib only — nothing to pip install).

git clone <this-repo-url> ~/repos/agent-factory
cd ~/repos/agent-factory
python -m unittest discover -s tests   # sanity check

Then either:

• Try an example first (recommended) — see examples/ for three complete, runnable agents. examples/agent-daily-digest needs nothing but claude authenticated; run it by hand with python examples/agent-daily-digest/run.py.
• Create your own — open this repo in Claude Code and run /new-agent. It'll ask what the agent should do, map what it needs to the tool catalog, stamp a new agent-<name> repo next to this one, and hand you a SETUP.md checklist for secrets and scheduling.

Examples

Agent	Style	What it needs
agent-daily-digest	pipeline	Nothing but claude — fetches public feeds/URLs, writes a summarized Markdown digest.
agent-security-branch-audit	agentic	git (and optionally gh) — reviews a branch's diff against a base branch for OWASP-style issues.
agent-inbox-priority	pipeline	Your own gog Google auth — ranks today's unread mail against upcoming meetings into a priority list.

Full walkthrough and adaptation notes: examples/README.md.

How it fits together

catalog/tools.toml   ──┐
templates/agent/     ──┼──►  runner/scaffold_agent.py  ──►  agent-<name>/ (new repo)
registry.toml         ─┘                                          │
                                                                    ▼
                                             runner/sync_orca.py ──► Orca schedule

Design rationale and the reasoning behind pipeline vs agentic, the run contract, and the secrets model: docs/ARCHITECTURE.md.

Bring your own credentials

Nothing in this repo talks to any account of the original author. Every example that needs a real integration (Gmail/Calendar via gog, GitHub via gh/a PAT) has its own SETUP.md that tells you exactly what to authenticate and where the result goes — env vars in a file outside the repo, never hardcoded, never in a prompt or a commit.

Contributing

Issues and PRs welcome — especially new catalog/tools.toml entries and new example agents. Keep new tools headless = true or clearly marked otherwise; scheduled runs must never depend on an interactive session.

License

MIT — see LICENSE.