If Claude Code is the doer, aweek is the planner.
Read the docs → · Quickstart · Recipes · Skills reference
aweek is a Claude Code plugin for building a team of AI agents that handle the work that repeats. Each agent has a role, a weekly plan, and a token budget. The plan evolves every Monday based on what worked last week. You set direction. Claude Code does the work. aweek runs the week.
aweek.mp4
Most AI tools are great at one-off prompts. They're terrible at the work that repeats — the weekly competitive scan, the Monday newsletter, the customer feedback digest, the recurring research memo. That work doesn't need a smarter model. It needs a team that shows up on schedule, remembers what they did last week, and gets a little better each Monday.
aweek is that team.
- Founders running their own ops who can't keep up with weekly cadence
- Marketers and creators publishing on a schedule (blog → social → newsletter)
- Analysts and researchers running weekly digests, briefs, or memos
- Anyone whose week looks a lot like last week's
A single agent on a calendar — sixteen scheduled tasks across five days, a daily review that closes each day, and a weekly review that ties the week to the month's goals. One budget, one cumulative plan.md, fresh Markdown in your repo every week.
| Mon | Tue | Wed | Thu | Fri | |
|---|---|---|---|---|---|
| 7am | Brief | Outreach | Interviews | Roadmap | — |
| 9am | Inbox | — | — | — | Feedback |
| 10am | — | Metrics | — | — | — |
| 11am | — | — | Content | Issues | Numbers |
| 3pm | — | — | — | — | Retro |
| 5pm | Daily | Daily | Daily | Daily | Weekly |
Full recipe → A weekly operator
- An engineer — handles the engineering periphery: PR triage, dep drift, flaky tests, doc drift, retros. Never ships features.
- A content marketer — grooms the topic queue, drafts the post, atomizes it for social, writes the newsletter, reviews analytics.
| You run | Your team does |
|---|---|
aweek hire |
Adds an agent — name, role, system prompt (auto-bootstraps on first run) |
aweek plan |
Drafts long-term goals → monthly objectives → weekly tasks. You approve. |
aweek summary |
Hands in a status report — done, pending, budget left |
aweek calendar |
Shows the week as an editable calendar grid |
aweek manage |
Lifecycle ops — pause, resume, top up budget, fire |
aweek delegate-task |
Drops work into another agent's inbox. Agents hand off to each other. |
aweek setup |
Explicitly bootstrap the project (usually auto-called by the first skill you run) |
aweek teardown |
Remove the heartbeat and/or .aweek/ data from a project |
/plugin install aweek@runbear-io # once published
aweek hire # add your first agent (auto-bootstraps heartbeat)
aweek plan # draft & approve the weekWalk away. Come back Monday morning to a status report and next week's draft plan.
- Skills (invoked via
aweek [name]) shell out to a tinyaweekCLI for every state change. - Heartbeat is a 10-minute launchd user agent per project. It picks the next pending task per agent and runs it in a fresh coding-agent CLI session — Claude Code by default, or the Gemini CLI / Hermes Agent when you set the runner (see below).
- Storage is plain files:
.aweek/agents/<slug>.jsonfor scheduling,.claude/agents/<slug>.mdfor identity. No DB.
Every mutation is schema-validated and atomic. 2,000+ tests guard the data layer.
aweek ships as a Claude Code plugin. The plugin's SessionStart hook installs the aweek CLI on first run.
From a Claude Code marketplace (when published):
/plugin install aweek@runbear-ioFrom source:
git clone https://github.com/runbear-io/aweek.git
cd aweek && pnpm install && pnpm link --global
claude --plugin-dir ./reload-plugins picks up edits without restarting.
Requirements: macOS 10.15 (Catalina) or newer, Node.js 20+. Linux and Windows aren't supported yet — the heartbeat installs as a launchd user agent.
By default the heartbeat runs each task with the Claude Code CLI. You can switch a project (or a single agent) to the Gemini CLI or the Hermes Agent instead:
aweek config # pick the `runner` knob → claude | gemini | hermesrunner is the project-wide default in .aweek/config.json; an individual agent can override it with its own runner field in .aweek/agents/<slug>.json (per-agent wins). Either way the agent's .claude/agents/<slug>.md stays the single source of truth for identity — for Gemini it's injected as the system prompt via the GEMINI_SYSTEM_MD env var; for Hermes it's embedded at the head of the one-shot prompt.
The runner applies across every surface that runs an agent: the scheduled heartbeat, aweek run-once, the dashboard chat panel, and Slack conversations (aweek serve). Slack is project-level, so it uses the .aweek/config.json runner; because Gemini/Hermes can't resume a headless session by id, aweek keeps each Slack thread's memory by replaying the stored conversation transcript into every turn.
Under the heartbeat, gemini and hermes both run in no-permission (YOLO) mode — there's no TTY at a scheduled tick to answer approval prompts (gemini --yolo --skip-trust, hermes --yolo --accept-hooks).
geminirequires thegeminiCLI on yourPATHand Gemini auth (e.g.GEMINI_API_KEYor OAuth login).hermesrequires thehermesCLI on yourPATHand a provider configured viahermes setup. Note: Hermes one-shot mode reports no token usage, so weekly-budget accounting is skipped for Hermes agents.
aweek doesn't manage Gemini or Hermes credentials.
Drop a .env file at .aweek/agents/<slug>/.env to give one agent its own environment variables. The heartbeat loads it on every tick and passes the values into that agent's Claude Code session — other agents don't see them.
# .aweek/agents/writer/.env
OPENAI_API_KEY=sk-...
NOTION_TOKEN=secret_...
FEATURE_FLAG=enabledFormat is dotenv-style: KEY=value, # comments, single/double quotes (double-quoted values support \n \r \t \\ \"). .aweek/ is gitignored, so secrets stay out of the repo by default.
- Skills don't show up in Claude Code. SessionStart's
npm install -g aweekfailed. Run it yourself. - Heartbeat isn't running. Check
launchctl list | grep io.aweek.heartbeat. If nothing matches, runaweek setupand confirm when prompted. - Agent paused. It hit its weekly budget.
aweek manage→resume(resets next week) ortop-up(resets now).
pnpm test # 2,000+ tests
pnpm lint # syntax-check srcSkills call into src/skills/*.ts via aweek exec <module> <fn>. Don't duplicate logic in ad-hoc node -e snippets — extend the module and register it in src/cli/dispatcher.ts.
Apache 2.0 — © 2026 Runbear, Inc.
Claude Code does the work. aweek runs the week.