Automations

An automation is a saved prompt + agent + recurring schedule. Codemux runs it for you — on a schedule, on a machine you choose — and each run spins up a fresh git worktree with the agent already working inside it.

Use it for the work that should just happen: triage new issues every morning, bump dependencies every Monday, summarize the week's PRs every Friday.

Automations are account-bound, so every device you sign into sees the same list.

Where To Find It

The left sidebar has an Automations button (the calendar-clock icon) right under New agent. It opens a full-screen Automations view — a list of your automations on the left, a detail pane on the right.

Anatomy Of An Automation

Each automation has:

• Name — what it's for, e.g. "Morning issue triage".
• Prompt — the instructions handed to the agent on every run.
• Agent — which CLI agent runs the prompt (Claude Code or Codex).
• Project — the repository the run works in. The picker lists the projects you currently have open in Codemux (alphabetically), so it mirrors the sidebar instead of every repo you've ever opened. An Other path… option still lets you point an automation at a repo that isn't currently open.
• Host — the machine the schedule fires on (see Where It Runs).
• Schedule — when and how often it runs.

The Schedule

The schedule builder covers the common cases without you touching syntax:

• Frequency — daily, weekly, and so on.
• Time of day — when the run fires.
• Weekdays — which days, for weekly schedules.

Under the hood the schedule is a standard RFC 5545 iCalendar rule (the same RRULE format calendar apps use), and it is timezone-aware — including daylight-saving transitions. If you need something the builder doesn't express, there's a raw RFC 5545 escape hatch where you can write the rule directly.

Pausing an automation stops it from firing. Resuming it recomputes the next run from now, so a paused automation never fires a backlog of missed runs all at once.

Where It Runs

Every automation targets one host — the machine its schedule fires on.

This machine

The default. The schedule fires on your own computer, in a background task inside the Codemux app. Because the scheduler lives in the app, a "This machine" automation only fires while Codemux is running. If the app was closed at fire time, the run is recorded as skipped_offline when you next open it.

A remote host

Point an automation at a registered remote host — an always-on VPS or home server — and it fires there instead, whether or not your laptop is open.

This needs two things on the host:

1. The scheduler service. When you install the codemux-remote helper on a host (the Install button in Settings → Hosts), Codemux also registers a small background service that runs the schedule. It's a systemd user service, so it survives host reboots.
2. The host's own GitHub credentials. A remote host gets the project by cloning its git remote with the host's own git and gh credentials — Codemux never injects a token. So the host needs working git auth (an SSH key or credential helper) and, for any issue/PR work, an authenticated gh.

A project with no git remote can only target This machine.

Preflight checks

Codemux flags credential problems at setup time instead of letting them surface at the first 9am run:

• Test connection in Settings → Hosts probes the host for git and gh auth status.
• The New Automation form runs a per-repo check — can this host actually reach this repository? — with a Check again button.

Both are informational. Neither blocks you from saving the automation.

What Happens On A Run

When a schedule fires:

1. Codemux creates an isolated git worktree off the project on a fresh branch (automation-<name>-<timestamp>).
2. It runs the agent headlessly in that worktree with your prompt.
3. When the agent finishes, the run is recorded with a real terminal status.

If a run is still going when the next one is due, the new run is skipped (skipped_busy) rather than stacked on top — the next scheduled occurrence is the natural retry. Different automations still run concurrently with each other; only the same automation is serialized.

Whether a run commits, pushes a branch, or opens a PR is up to your prompt — write "commit and open a PR" into the prompt if you want that. Codemux records whatever branch and PR result.

Run History

Each automation keeps a run history. A run is one of:

Run rows are kept indefinitely, so the history survives even after the worktrees age out. Each automation in the list also shows a health dot driven by its most recent run — green when healthy, amber when the last run failed, grey when paused. Fix a misconfigured host and the next run clears the dot on its own.

If a host or the app crashes mid-run, a reconciler marks the abandoned run as failed at the next scheduler start, so a dead run can't pin its automation in skipped_busy forever.

Account Sync

Your automations sync through your Codemux account, so creating one on your laptop makes it appear on your desktop too. Run history is per-device — each machine keeps the history for the runs it can see.

Current Limitations

• No run-now. You can't trigger an off-schedule run on demand yet; an automation fires only on its schedule.
• Worktree cleanup isn't automatic yet. Each automation has a retention setting, but the cleanup that prunes old run worktrees from the host isn't implemented — run worktrees currently accumulate.
• Hosts use a full account token. The scheduler on a remote host authenticates with a copy of your account token. A narrower per-host token is planned.

Related

• Settings → Hosts — register remote hosts and install the codemux-remote helper
• Projects — the repositories an automation can target
• MCP Server — automation_* tools let an agent manage automations programmatically
• Workspaces — how Codemux worktrees and workspaces work