# OpenHelm, full documentation

OpenHelm runs scheduled, self-correcting AI agent jobs, driven over a REST API (/v1) or remote MCP servers. Below is the complete documentation as clean markdown.


# Getting Started


## Installation
Source: https://openhelm.ai/docs/installation
## System Requirements

- macOS 13 (Ventura) or later
- Apple Silicon or Intel Mac
- Claude Code v2.0.0 or later, installed and authenticated

No other dependencies required, the app is fully self-contained.

## Download

Download the correct build for your Mac from the [releases page](https://github.com/maxbeech/openhelm/releases):

- **Apple Silicon (M1/M2/M3/M4):** `OpenHelm_0.1.0_aarch64.dmg`
- **Intel Mac:** `OpenHelm_0.1.0_x64.dmg`

If you're unsure which chip you have: Apple menu → About This Mac → look for "Apple M" (Silicon) or "Intel" in the chip/processor line.

## Install

1. Open the downloaded `.dmg` file
2. Drag **OpenHelm** into your **Applications** folder
3. Launch from Applications (or Spotlight)

On first launch, macOS may show a security prompt for an unverified developer. If that happens: System Settings → Privacy & Security → scroll to the Security section → click **Open Anyway**.

## Setting Up Claude Code

OpenHelm requires Claude Code to be installed and authenticated on your machine.

1. [Install Claude Code](https://claude.ai/code) if you haven't already
2. Run `claude` in your terminal at least once to complete authentication
3. On first launch, OpenHelm auto-detects Claude Code in your PATH, Homebrew, and global npm paths

If Claude Code is installed in a non-standard location, go to **Settings → Claude Code Path** and set the path manually.

## Verify Setup

On first launch, OpenHelm shows a setup screen. Once Claude Code is detected and a green checkmark appears next to the version, you're ready to create your first project.

## Uninstall

Drag **OpenHelm** from your Applications folder to the Trash. All app data is stored in `~/Library/Application Support/ai.openhelm.app/`, delete this directory to fully remove all data.


## Quick Start
Source: https://openhelm.ai/docs/quick-start
## 1. Create a Project

A project links OpenHelm to a directory on your Mac. Click **New Project** in the sidebar, give it a name, and select the directory Claude Code will work in.

## 2. Set a Goal

Click **New Goal** and describe what you want in plain English. OpenHelm uses AI to turn your description into a structured job plan, or you can skip the planner and create jobs manually.

**Using the AI planner:**
Type your goal (e.g., "Run weekly SEO audits on my website and fix any issues found") and click **Generate Plan**. The AI creates a structured job plan with suggested schedules. Review each job, tweak if needed, then click **Approve Plan**.

**Creating jobs manually:**
Click **Build manually** to create jobs directly, write your prompt, pick a schedule type, and save.

## 3. Jobs Run on Schedule

Once approved, jobs run automatically according to their schedules. A job set to run daily at 2am will fire at 2am, the app can run in the background while you're away.

> **Note:** OpenHelm's scheduler runs while the app is open. Your Mac must also be awake when a job is scheduled to fire. For reliable unattended automation, keep your Mac plugged in and configure Energy Saver to prevent sleep, or use a Mac that stays on (Mac mini, Mac Studio).

## 4. Monitor Runs

Click any job to see its run history, status, duration, logs, and exit code. Failed runs surface in the **Inbox** tab with options to retry, adjust, or dismiss.

## 5. Trigger a Run Immediately

To test a job right now, click **Run now** on any job. The run is queued at highest priority and starts within the next scheduler tick (up to 60 seconds).


## Requirements
Source: https://openhelm.ai/docs/requirements
## Claude Code Requirements

OpenHelm runs Claude Code as its execution engine. You need:

- Claude Code **v2.0.0 or later**
- An active Anthropic account with API access
- Claude Code authenticated (`claude` must work in your terminal)

OpenHelm auto-detects Claude Code in the following locations:
- System `PATH`
- Homebrew (`/opt/homebrew/bin/claude`, `/usr/local/bin/claude`)
- Global npm installations

If your Claude Code binary is in a custom location, set it manually in **Settings → Claude Code Path**.

## macOS Permissions

OpenHelm is a standard macOS desktop application. On first launch, macOS may request:

- **Notifications** (optional), to notify you when jobs complete or fail

No other special permissions are required.

## Hardware

- macOS 13 (Ventura) or later
- Apple Silicon (M1 or later) or Intel Mac
- Recommended: 8 GB RAM when running multiple jobs concurrently

## Running Jobs Unattended

OpenHelm's scheduler runs while the app is open. For fully automated background execution:

- Keep the app running in the background, it uses minimal resources when idle
- Ensure your Mac does not sleep during scheduled job windows
- For reliable overnight automation, use a Mac that stays on (Mac mini, Mac Studio), or configure your MacBook's Energy Saver settings to prevent sleep when plugged in


# For Developers


## API Quickstart
Source: https://openhelm.ai/docs/api-quickstart
OpenHelm gives AI agents and your own backend a single place to run **hard, multi-step jobs**, work that takes minutes, hours, or runs on a schedule. Two front doors share one engine:

- **REST API** (`/v1`), call it server-to-server from your product.
- **MCP servers**, connect a remote URL from ChatGPT, Claude or Cursor (see [MCP servers](/docs/mcp-servers)).

Both run work in isolated cloud sandboxes and return the same structured, evidence-backed result.

## 1. Get a key

Create a Bearer key (`oh_live_…`) under **Settings → API & Webhooks** in your OpenHelm account. The key is shown once.

## 2. Run a task in one call

```bash
curl https://api.openhelm.ai/v1/runs \
  -H "Authorization: Bearer oh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Get the pricing tiers from stripe.com",
    "output_schema": {
      "type": "object",
      "properties": { "tiers": { "type": "array", "items": { "type": "string" } } }
    }
  }'
```

> The base URL shown in the [live API reference](/docs/api) is the source of truth, it is generated from the deployed OpenAPI spec.

The response is **202 Accepted** with a `task_id`, a `poll_url`, and a `billing` cost estimate:

```json
{
  "task_id": "run_2x9f4c...",
  "poll_url": "https://api.openhelm.ai/v1/runs/run_2x9f4c...",
  "billing": { "model": "sonnet", "estimated_cost_usd": { "low": 0.05, "high": 0.3 } }
}
```

## 3. Collect the result

Poll `GET /v1/runs/{id}` until `status` is terminal, or supply a `callback_url` to get a webhook instead (see [Long-running & recurring jobs](/docs/long-running-jobs)). The completed envelope carries your structured `result`, `evidence`, `confidence`, and `usage.cost_usd`.

## What next

- [Authentication & API keys](/docs/authentication)
- [Runs & the result envelope](/docs/runs-and-results)
- [Connections API](/docs/connections-api), give a task the credentials it needs
- [Pricing & credits](/docs/pricing-credits)


## Authentication & API keys
Source: https://openhelm.ai/docs/authentication
Every `/v1` request authenticates with a Bearer API key.

```
Authorization: Bearer oh_live_...
```

## Keys

- Mint, name, and revoke keys under **Settings → API & Webhooks** (org owners/admins).
- Keys are **org-scoped**. The full secret is shown once; OpenHelm stores only its SHA-256 hash.
- `oh_live_…` runs against your real plan; `oh_test_…` is for test wiring.
- Each key carries a **webhook signing secret** used to verify completion webhooks.

## Guardrails on a key

- **Monthly cap**, set `monthly_cap_usd` per key; spend beyond it returns `402`.
- **Project allowlist**, scope a key to specific projects.

## The MCP servers reuse your key

When you connect an [MCP server](/docs/mcp-servers), the "Connect with OpenHelm" OAuth flow wraps your encrypted key in a signed token. The servers are stateless and store no secrets.

## Errors

HTTP `4xx/5xx` is reserved for request, auth, and quota problems (`401` invalid key, `402` quota/subscription gate, `403` out-of-scope, `429` too many concurrent runs). A **task** that fails returns `200`/`202` with a structured `failure_reason`, see [Runs & the result envelope](/docs/runs-and-results).


## Runs & the result envelope
Source: https://openhelm.ai/docs/runs-and-results
## Starting a run

- `POST /v1/runs`, an **inline run** from a prompt (the one-call primitive).
- `POST /v1/jobs/{id}/runs`, run a **saved job** (a reusable template whose prompt carries `{{placeholders}}`).

Body fields: `prompt` (or the job's), `inputs` (fills `{{placeholders}}`), `output_schema` (JSON Schema for the shape you want back), `model` (`haiku` | `sonnet` | `opus`, default `sonnet`), `project_id` (optional, defaults to your org's auto-created **API Runs** project), `callback_url`, and `idempotency_key`.

## The result envelope

`GET /v1/runs/{id}` returns:

```json
{
  "task_id": "run_...",
  "status": "queued | running | succeeded | failed | cancelled",
  "result": { /* your output_schema shape, or null */ },
  "confidence": "high | medium | low | null",
  "evidence": { "screenshot_url": "…7-day signed URL…", "matched_text": "…", "checked_at": "…" },
  "failure_reason": "captcha | auth_required | site_down | timeout | ambiguous | not_found | null",
  "usage": { "duration_ms": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": 0 },
  "created_at": "…", "finished_at": "…"
}
```

- **`result`** conforms to your `output_schema` on a best-effort basis.
- **`evidence`** lets you verify what the agent actually saw.
- **`failure_reason`** is explicit, OpenHelm never fabricates a result. `auth_required` means the task needed a [connection](/docs/connections-api) that isn't set up.
- **`usage.cost_usd`** is the **actual billed cost** (the 202 `billing` block was only an estimate).

## Idempotency

Pass `idempotency_key` to make retries safe, a replay returns the original run instead of starting a new one.


## Long-running & recurring jobs
Source: https://openhelm.ai/docs/long-running-jobs
OpenHelm runs are asynchronous. There are three ways to consume results, matched to how long the work takes.

## 1. Seconds, inline

Fast tasks settle quickly. Over MCP, the tool call bounded-waits (~75s) and returns the result in one turn; if it isn't ready it returns a `task_id` and you call `check_result`.

## 2. Minutes to hours, poll or webhook

`POST /v1/runs` returns **202** immediately with a `task_id` and `poll_url`. Either:

- **Poll** `GET /v1/runs/{id}` until `status` is terminal, or
- Supply a **`callback_url`** and receive an HMAC-signed webhook on completion.

### Verifying the webhook

The body is `{ "event": "run.completed" | "run.failed", "data": <TaskEnvelope> }`. The signature header is Stripe-style:

```
X-OpenHelm-Signature: t=<unix_seconds>, v1=<hex>
signed_payload = `${t}.${rawBody}`
expected = HMAC_SHA256(api_key.signing_secret, signed_payload)
```

Reject anything that doesn't match, and de-dupe on `data.task_id` (deliveries can repeat).

## 3. Recurring, register once, receive forever

Create a **scheduled job** (`schedule_type` of `interval`, `cron`, or `email`) and it fires your webhook on **every run**. A long-lived monitor (a daily briefing, an inbox watcher, a weekly report) streams results back for weeks with no polling. List a job's history with `GET /v1/runs?job_id=…`.

> Tip: webhooks beat polling for anything time-sensitive. Acknowledge fast (2xx), then process out-of-band.


## Connections API
Source: https://openhelm.ai/docs/connections-api
A **connection** is a credential or tool a run can use, a Gmail account, a GitHub token, a remote MCP server, an OAuth provider. Provision them without the dashboard.

## Direct: token & MCP connections

```bash
# Store an API key/secret (encrypted in Vault)
curl https://api.openhelm.ai/v1/connections \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "GitHub PAT", "type": "token", "secret": "ghp_...", "env_var_name": "GITHUB_TOKEN" }'

# Register a remote HTTP/SSE MCP server (headers may use ${SECRET})
curl https://api.openhelm.ai/v1/connections \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "Acme MCP", "type": "mcp", "url": "https://acme.example/mcp",
        "transport": "http", "headers": { "Authorization": "Bearer ${SECRET}" }, "secret": "..." }'
```

Scope a connection to one project with `project_id`, or omit it to make it available to all the account's runs. The stored secret is **write-only**, it is never returned by `GET /v1/connections`.

## Hosted link: OAuth providers

Providers that need a browser (Google, Notion, LinkedIn…) can't be created from a raw key. Mint a short-lived link instead:

```bash
curl https://api.openhelm.ai/v1/connections/links \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "provider": "google" }'
# → { "url": "https://app.openhelm.ai/connections?add=google&grant=…", "expires_at": "…" }
```

Open the URL (signed in to the account that owns the key), complete authorisation, then poll `GET /v1/connections` until it shows `auth_status: "authenticated"`.

## When a run needs a connection that isn't there

The run fails with `failure_reason: "auth_required"`, OpenHelm tells you what's missing rather than guessing. Set up the connection and re-run.


## MCP servers
Source: https://openhelm.ai/docs/mcp-servers
The OpenHelm MCP servers wrap the same `/v1` engine so any MCP client can drive it, no code. They are remote, Streamable-HTTP servers; you add a URL.

## The servers

| Server | URL | For |
|---|---|---|
| General-purpose | `https://mcp.openhelm.ai/main/mcp` | Raw run/job/connection primitives |
| Deep research | `https://mcp.openhelm.ai/research/mcp` | Company diligence, filings, comps |
| SEO & GEO | `https://mcp.openhelm.ai/seo/mcp` | Keyword + content + AI-citation |
| Email outreach | `https://mcp.openhelm.ai/email/mcp` | Send + handle replies |
| Dev changes | `https://mcp.openhelm.ai/dev/mcp` | Open PRs, review, deps |

See each on the [MCP & API hub](/mcp).

## Connect

- **ChatGPT / Claude / Cursor:** add the URL as a remote connector. Approve the "Connect with OpenHelm" prompt (a card starts your free trial).
- **stdio-only clients (Claude Desktop):** bridge it:

```json
{ "mcpServers": { "openhelm": { "command": "npx",
  "args": ["-y", "mcp-remote", "https://mcp.openhelm.ai/main/mcp"] } } }
```

## Long-running tasks

The servers bounded-wait ~75 seconds, then return a `task_id`; your assistant calls `check_result` to retrieve the finished output, so a connection never hangs mid-run.


## Pricing & credits
Source: https://openhelm.ai/docs/pricing-credits
API and MCP usage draws from the **same credits** as the rest of your OpenHelm plan, there is no separate developer bill.

- **1 credit = $0.05** of billed cost (a 20% markup is included).
- Every started run returns a `billing` **estimate** (per-model band + your monthly cap). The **actual** cost is `usage.cost_usd` on the completed run.
- **Per-key monthly cap** (`monthly_cap_usd`) and an **org daily cap** bound spend defensively.
- New accounts add a card to start a **free trial**, you're not charged during it. This protects shared cloud compute from multi-account abuse on the public MCP servers.

Manage your plan and usage under **Settings → Plan** and **Settings → Usage**.


## Deep research guide
Source: https://openhelm.ai/docs/guides/deep-research
Deep research covers one-off diligence and recurring briefings, grounded in official sources (SEC EDGAR, the live web), never fabricated.

## From an assistant (MCP)

Connect `https://mcp.openhelm.ai/research/mcp` and call tools like `deep_research_company`, `earnings_triage`, `build_comp_set`, `monitor_sec_filings`, or `morning_notes`. Longer runs return a `task_id`; call `check_result`.

## As a recurring monitor

Adopt the **Hedge Fund Deep Research** or **Thesis-Aware Morning Briefing** strategy in the app, or create a `cron` job over the API and supply a `callback_url`, you'll get a webhook every morning. See [Long-running & recurring jobs](/docs/long-running-jobs).

> Disclosed trades are lagged and outputs are not investment advice.


## SEO & GEO guide
Source: https://openhelm.ai/docs/guides/seo-geo
The SEO & GEO server automates organic growth across traditional search **and** AI answer engines.

## Tools

Connect `https://mcp.openhelm.ai/seo/mcp`: `find_keyword_opportunities`, `keyword_research`, `write_seo_blog_post`, `audit_onpage_seo`, `audit_technical_seo`, `seo_progress_report`, plus GEO tools `track_ai_answer_visibility`, `optimize_content_for_ai_citation`, and `geo_competitor_mentions`.

## Connections

GSC and keyword data need real connections, set up Google Search Console and Google Ads (see [Connections API](/docs/connections-api)). The agent uses **real data only**: if GSC isn't connected it says so and stops rather than inventing numbers.

## Recurring

Adopt the **Free-Tools SEO Growth** strategy for weekly publishing, audits, and reports on a schedule.


## Email outreach guide
Source: https://openhelm.ai/docs/guides/email-outreach
Unlike an inbox API, OpenHelm **runs the conversation**: research, send, then triage and respond to replies.

## Tools

Connect `https://mcp.openhelm.ai/email/mcp`: `research_recipient`, `draft_outreach_email`, `send_outreach_email`, `triage_inbox`, and `draft_reply`.

## Connections

Set up an email connection (Gmail, or your org's `relay.openhelm.ai` identity) so the agent can send and read replies. Reply detection runs **before** any new send, and the agent escalates rather than guessing when a reply asks something it can't verify.

## Always-on

Adopt the **Email Outreach & Reply Handling** strategy for recurring sequences and a scheduled reply sweep. Real data only, it never fabricates a recipient, a send, or a fact about your organisation.


## Dev changes guide
Source: https://openhelm.ai/docs/guides/dev-changes
Describe a change; an agent clones the repo, makes a focused edit, runs the project's tests, **pushes first**, and opens a PR.

## Tools

Connect `https://mcp.openhelm.ai/dev/mcp`: `open_pull_request`, `propose_change`, `triage_issue`, `review_pull_request`, and `dependency_audit`.

## Connections

Set up a **GitHub** connection (and, in cloud, the repo's git URL). The agent secures work by pushing before any heavy build, and opens one focused PR per change.

## Externalised fixes

If a request can only be fixed outside the code, missing credentials, an ambiguous spec, a product decision, the agent **refuses and explains the external fix** rather than hacking around it. It never fabricates a PR URL or a passing test.

## Recurring

Adopt the **Repo & Developer Changes** strategy for scheduled dependency upkeep and housekeeping PRs.


# Core Concepts


## Projects & Goals
Source: https://openhelm.ai/docs/concepts/projects-and-goals
## Projects

A project is a named workspace linked to a directory on your Mac. Claude Code runs within the project's directory, it can read and modify files there according to the jobs you define.

Create a project from the sidebar: click **New Project**, give it a name, and select the directory.

## Goals

A goal is a high-level objective you want to achieve in a project. Goals contain one or more jobs, scheduled tasks that Claude Code executes to work toward that objective.

**Goal statuses:**
- `active`, goal is live; its jobs run on schedule
- `paused`, goal is temporarily suspended; no new runs start
- `archived`, goal and all jobs are preserved but inactive

## AI-Generated Goals

Describe your goal in plain English and let the AI planner structure it into a concrete job plan. The planner generates 2–6 jobs with suggested prompts, schedules, and rationale.

You review the entire plan before anything runs, approve as-is, edit individual jobs, or start over.

## Manual Goals

Skip the AI planner entirely and build your own job list. This is the right choice when you know exactly what you want to automate and don't need the AI to interpret your goal.

## Writing Effective Goal Descriptions

The quality of the AI-generated plan depends on the clarity of your description.

**Be specific about the outcome, not the steps:**

```
Good: "Run a weekly audit of the /blog section for broken links, outdated content, and
missing meta descriptions. Create a GitHub issue summarising each finding."

Less useful: "Check my website"
```

**Include relevant constraints:**
- "Don't touch files in the /vendor directory"
- "Open a PR if changes pass tests; otherwise open an issue"
- "Only report issues; don't automatically fix them"


## Jobs
Source: https://openhelm.ai/docs/concepts/jobs
## What Is a Job?

A job is a scheduled, executable task. When a job fires, OpenHelm runs Claude Code with the job's prompt in the project directory. Jobs are the atomic unit of work in OpenHelm.

Each job has:

- **Name**, human-readable label
- **Prompt**, instructions sent to Claude Code when the job runs
- **Schedule**, when and how often to run (see [Schedule Types](/docs/scheduling/schedule-types))
- **Model settings**, which Claude model to use and effort level
- **Permission mode**, how much autonomy Claude Code has during execution

## Creating Jobs

Jobs can be created two ways:
1. **Via the AI planner**, describe a goal; the AI generates a job plan for you to review and approve
2. **Manually**, click **New Job** and fill in the prompt, schedule, and settings yourself

## Job Settings

### Model
The Claude model used for this job's execution. Defaults to Claude Sonnet 4.6.

### Effort (`low | medium | high`)
Controls how much planning effort Claude Code uses before starting work. Higher effort means more thorough planning but more tokens consumed.

### Permission Mode
Controls what Claude Code can do without prompting for confirmation:
- `default`, standard Claude Code permissions
- `acceptEdits`, auto-accepts file edits without prompting
- `dontAsk`, does not prompt for confirmation on most actions
- `bypassPermissions`, maximum automation; use with care

### Working Directory Override
By default, jobs run in the project's root directory. Override this to run in a specific subdirectory or a different path entirely.

### Correction Note
Optional text appended to the prompt of any corrective retry run. Use this to guide Claude Code when recovering from failures, for example, specifying which commands to run first or which files to check.

## Enabling and Disabling Jobs

Toggle the switch on any job to pause or resume automatic scheduling. Disabled jobs can still be triggered manually.


## Runs
Source: https://openhelm.ai/docs/concepts/runs
## What Is a Run?

A run is a single execution attempt of a job. Every time a job fires, on schedule, manually triggered, or as a corrective retry, a new run record is created.

## Run Statuses

| Status | Meaning |
|--------|---------|
| `deferred` | Manually triggered for a future time; waiting to start |
| `queued` | Waiting for an available executor slot |
| `running` | Claude Code is actively executing |
| `succeeded` | Completed successfully (exit code 0) |
| `failed` | Completed with an error (non-zero exit code) |
| `permanent_failure` | Pre-flight check failed (e.g. binary not found, project directory missing) |
| `cancelled` | Cancelled by the user before or during execution |

## Viewing Runs

Click any job to see its run history. Each run shows:
- Status and duration
- Start and finish timestamps
- Full stdout/stderr log stream
- Exit code and trigger source (scheduled, manual, or corrective)

## Triggering Runs Manually

Click **Run now** on any job to immediately queue a run. Manual runs are given the highest priority and execute before any scheduled or corrective runs.

You can also defer a manual run to a specific future time, useful for queuing work without changing the job's recurring schedule.

## Cancelling Runs

Click **Cancel** on any queued or running run:
- **Queued runs**, removed from the queue immediately
- **Running runs**, Claude Code receives SIGTERM; after a 5-second grace period, SIGKILL is sent if it hasn't stopped

## Resuming Runs in Terminal

Every completed run records a Claude Code session ID. Click **Open in Terminal** on a completed run to launch Terminal, navigate to the project directory, and resume the session interactively with `claude --resume <sessionId>`. This lets you pick up where Claude Code left off or inspect what it did.

## Clearing Run History

Run history is kept indefinitely. To clear history for a specific job, use **Clear history** in the job's settings menu.


## Licensing
Source: https://openhelm.ai/docs/concepts/fair-source
## The OpenHelm Licence

OpenHelm is commercial software with a generous free tier. Most personal and small-team use is free; commercial deployment and redistribution require a commercial licence.

## What You Can Do

- Download and run OpenHelm for personal and commercial _use_
- Use it across as many of your own projects as you like

## What Requires a Commercial License

- Offering OpenHelm as a hosted/managed service to others
- Redistributing OpenHelm as part of a commercial product

## Pricing Tiers and Licensing

- **Community**, Free for personal use, students, non-profits, and startups under $1M revenue
- **Business**, $19/user/month. Commercial use license, self-hosted, priority support _(coming soon)_
- **Cloud**, $39/month. Managed hosting, team sharing, enterprise security _(coming soon)_

See the [Pricing page](/pricing) for full details.


# Scheduling


## Schedule Types
Source: https://openhelm.ai/docs/scheduling/schedule-types
## Five Schedule Types

OpenHelm supports five schedule types, selected when creating or editing a job.

---

### Once

Runs the job exactly once at a specific date and time, then never again.

| Field | Description |
|-------|-------------|
| Fire at | Date and time (local timezone) |

**When to use:** One-off migrations, initial setup tasks, or any work that should happen exactly once.

---

### Interval

Runs the job repeatedly at a fixed interval after the previous run completes.

| Field | Description |
|-------|-------------|
| Amount | A number |
| Unit | `minutes`, `hours`, or `days` |

**Example:** Every 24 hours, every 30 minutes, every 7 days.

**Note:** The interval is measured from the *completion time* of the previous run, not from the original fire time. This prevents queue pile-ups if a run takes longer than expected.

---

### Cron

Runs the job on a standard 5-field cron expression.

| Field | Description |
|-------|-------------|
| Expression | Standard cron format: `minute hour day month weekday` |

**Examples:**
```
0 9 * * 1-5      # 9am Monday–Friday
0 2 * * *        # 2am every day
0 0 1 * *        # midnight on the 1st of each month
*/30 * * * *     # every 30 minutes
```

Cron times are interpreted in your local timezone.

---

### Calendar

A human-friendly alternative to cron for common recurring patterns.

| Field | Description |
|-------|-------------|
| Frequency | `daily`, `weekly`, or `monthly` |
| Time | HH:MM (local time) |
| Days of week | (weekly only) which days to run, e.g. Mon, Wed, Fri |
| Day of month | (monthly only) which day, e.g. the 1st |

**Examples:**
- Daily at 2:00am
- Weekly on Monday and Thursday at 9:00am
- Monthly on the 1st at midnight

---

### Manual

The job has no automatic schedule, it only runs when you explicitly click **Run now**.

**When to use:** Jobs you want to control explicitly, ad-hoc tasks, or jobs that are part of a human-supervised workflow.

---

## How the Scheduler Works

OpenHelm's built-in scheduler checks for due jobs every **60 seconds**. When a job's next scheduled fire time falls within the current minute, the scheduler creates a queued run.

Jobs execute with configurable concurrency, by default one job at a time. Increase this to 2 or 3 in **Settings → Max Concurrent Runs** to run jobs in parallel.

## Next Fire Time

The scheduler tracks a `nextFireAt` timestamp for each job:

| Schedule type | How `nextFireAt` is updated |
|---------------|------------------------------|
| Once | Set to null after firing; never fires again |
| Interval | Set to completion time + interval after each run |
| Cron | Calculated as the next matching cron occurrence from now |
| Calendar | Calculated as the next matching calendar occurrence from now |
| Manual | Always null; never auto-fires |


## Manual Triggers
Source: https://openhelm.ai/docs/scheduling/manual-triggers
## Manual Triggers

Any job can be triggered immediately regardless of its schedule.

**Run now:** Click the **Run now** button on any job. The run is queued immediately at the highest priority and executes before any scheduled runs.

**Deferred trigger:** Trigger a run at a specific future time without changing the job's recurring schedule. Useful for scheduling a one-time urgent execution outside the normal cadence.

## Cancelling Runs

Cancel any queued or running run from the run detail view:

- **Queued runs**, removed from the queue immediately
- **Running runs**, Claude Code receives SIGTERM; after a 5-second grace period, SIGKILL is sent if it has not stopped

## Run Priority

Runs execute in priority order:

| Priority | Trigger source | Notes |
|----------|---------------|-------|
| 0 (highest) | Manual | Runs triggered by **Run now** |
| 1 | Scheduled | Regular scheduled fires |
| 2 (lowest) | Corrective | Auto-generated self-correction retries |

Within each priority level, runs execute in FIFO order.

## Concurrency

By default, only one run executes at a time. Increase **Max Concurrent Runs** in Settings to 2 or 3 to allow parallel execution. This is useful when you have multiple independent projects running simultaneously.


# Features


## AI Planning
Source: https://openhelm.ai/docs/features/ai-planning
## How AI Planning Works

When you create a new goal, the AI planner turns your plain-English description into a structured job plan ready to review and approve.

### Step 1: Assessment

The AI first assesses whether your goal is clear enough to plan without clarification. If it needs more information, it asks up to two targeted questions (multiple-choice format with a free-text option).

### Step 2: Plan Generation

Once the goal is clear, the planner runs a full planning pass and returns a set of 2–6 jobs. Each proposed job includes:

- A descriptive name
- A concrete Claude Code prompt
- A suggested schedule type and configuration
- A rationale explaining why the job is structured this way

### Step 3: Review and Approval

You see the complete plan before anything executes. You can:

- Approve the plan as-is
- Edit individual jobs (change the prompt, schedule, name)
- Delete jobs you don't want
- Add additional jobs manually

Once you click **Approve Plan**, the goal and all its jobs are created in a single operation. Once-only jobs fire within the next scheduler tick; recurring jobs calculate their first fire time from the current moment.

## Planning Quality

The quality of the generated plan depends heavily on the clarity of your goal description. See [Projects & Goals](/docs/concepts/projects-and-goals) for guidance on writing effective goal descriptions.

## Skipping the Planner

Click **Build manually** at any point to skip AI planning and create jobs directly. The planner is a convenience, you always stay in full control.


## Self-Correction
Source: https://openhelm.ai/docs/features/self-correction
## Automatic Self-Correction

When a job run fails, OpenHelm can automatically create a *corrective run*, a follow-up execution that includes context about what went wrong and any correction guidance you've provided.

### How It Works

1. A run finishes with a non-zero exit code (failure)
2. OpenHelm queues a corrective run with the original prompt plus the failure context appended
3. The corrective run executes at the lowest priority, after all scheduled runs
4. If the corrective run also fails, the cycle repeats up to the configured retry limit
5. Once the retry limit is exhausted, the job is marked as `permanent_failure` and surfaced in the Inbox

### Correction Notes

Each job has an optional **Correction note** field. Text entered here is appended to the prompt of every corrective run for that job. Use this to provide guidance for recovering from the specific failures that job tends to encounter:

```
If tests fail due to missing dependencies, run `npm install` first.
Check .env.example for required environment variables that may need to be set.
```

### Configuration

Control self-correction in **Settings**:

| Setting | Description |
|---------|-------------|
| Auto-correction enabled | Toggle automatic corrective runs on or off |
| Max correction retries | How many times to retry before marking as permanent failure |

## The Inbox

The **Inbox** surfaces runs that require human attention, jobs that have exhausted their automatic retries, and any run where Claude Code explicitly requested human input.

For each inbox item, you can:

- **Dismiss**, acknowledge the failure and take no further action
- **Try again**, queue an immediate manual re-run with the original prompt
- **Do something different**, provide new instructions and queue a corrective run incorporating your guidance


## Memory System
Source: https://openhelm.ai/docs/features/memory-system
## Project Memory

OpenHelm maintains a semantic memory store per project. As goals and jobs are created and runs complete, information is extracted and stored, building up a knowledge base that informs future planning and execution.

## Memory Types

| Type | What it stores |
|------|---------------|
| `semantic` | Conceptual knowledge: API patterns, architecture, project conventions |
| `episodic` | Events and outcomes: what ran, what failed, what was learned |
| `procedural` | How-to knowledge: workflow steps and best practices discovered through runs |
| `source` | Original documents: code snippets and documentation excerpts |

## How Memory Accumulates

Memory is extracted automatically:

- When a goal is created (from the goal description)
- When a job is created (from the job prompt)
- After a run completes (from outputs and outcomes)

## Semantic Search

The memory system supports semantic search, finding relevant memories by meaning, not just keyword matching. This allows OpenHelm to surface related context even when the exact words don't match.

## Memory Tags

Memories are tagged for organisation and retrieval. Default tags include:

`goal`, `data-source`, `preference`, `workflow`, `error-pattern`, `tool-usage`, `architecture`, `convention`

## Viewing and Managing Memory

Access the memory store from the project sidebar under **Memory**. From there you can:

- Browse all memories for the project
- Search by text or tag
- Archive memories that are no longer relevant
- Prune low-importance memories automatically


## Data Export & Import
Source: https://openhelm.ai/docs/features/data-export
## Exporting Data

Export all your OpenHelm data to a portable JSON file via **Settings → Export Data**.

The export includes:
- Projects, goals, jobs
- Run history (and optionally, full run logs)
- Inbox items and conversations
- Memory store
- Settings (excluding machine-specific paths like the Claude Code binary location)

## Importing Data

Import a previously exported JSON file via **Settings → Import Data**.

**Preview before import:** OpenHelm shows you what the file contains, record counts, export date, and app version, before making any changes.

**Important:** Import is a full replacement. All existing data is overwritten with the imported data. This cannot be undone. The import is also blocked if there are any active or queued runs.

After import, machine-specific settings (like the Claude Code path) are automatically preserved from your current installation rather than overwritten.

## Migrating Between Machines

1. On your old Mac: **Settings → Export Data**
2. Transfer the export file to your new Mac (AirDrop, iCloud, USB, etc.)
3. Install OpenHelm on the new Mac
4. **Settings → Import Data** and select the file
5. If your project directories are in different locations on the new Mac, use **Settings → Fix Project Paths** to update them

## What's Not Included

- Claude Code itself and its authentication state (must be set up separately on the new Mac)
- The Claude Code binary path setting (re-detected automatically after import)


# Reference


## App Settings
Source: https://openhelm.ai/docs/reference/settings
## Accessing Settings

Click the gear icon in the sidebar, or use the **OpenHelm → Settings** menu item.

## Claude Code

| Setting | Description |
|---------|-------------|
| Claude Code path | Path to the `claude` binary. Auto-detected from PATH, Homebrew, and npm on first launch. |
| Detected version | Shows the currently detected Claude Code version. Minimum required: v2.0.0. |

To re-detect after updating Claude Code, click **Re-detect** next to the path field.

## Execution

| Setting | Description |
|---------|-------------|
| Max concurrent runs | How many jobs can run simultaneously: 1, 2, or 3. Default: 1. |
| Run timeout | Maximum minutes a run can execute before being force-stopped. Set to 0 for no limit. Default: no limit. |

## Notifications

| Setting | Description |
|---------|-------------|
| Notification level | `never`, no notifications; `on_finish`, notify on all completions and failures; `alerts_only`, notify only on failures. |

## Self-Correction

| Setting | Description |
|---------|-------------|
| Auto-correction enabled | Whether failed runs automatically generate corrective retries. |
| Max correction retries | Maximum number of corrective attempts before marking a run as permanent failure. |

## Analytics

| Setting | Description |
|---------|-------------|
| Analytics enabled | Send anonymised crash reports and usage data (powered by Sentry). Opt out at any time. |

## Data

| Action | Description |
|--------|-------------|
| Export data | Export all data to a JSON file for backup or migration. |
| Import data | Replace all data with a previously exported JSON file. |
| Fix project paths | Update project directory paths after migrating to a new machine. |


## Troubleshooting
Source: https://openhelm.ai/docs/reference/troubleshooting
## Claude Code Not Detected

**Symptom:** Setup screen shows Claude Code as not found, or a red warning in Settings.

**Solutions:**
1. Open Terminal and run `which claude`, if it returns a path, copy it and enter it manually in **Settings → Claude Code Path**
2. If `which claude` returns nothing, Claude Code is not installed. [Install it from claude.ai/code](https://claude.ai/code)
3. If installed via Homebrew or npm in a custom location, check those directories and set the path manually

## Claude Code Version Too Old

**Symptom:** OpenHelm reports your Claude Code version does not meet the minimum requirement (v2.0.0).

**Solution:** Update Claude Code. Run `claude update` in Terminal, or reinstall from [claude.ai/code](https://claude.ai/code).

## Jobs Not Running on Schedule

**Symptom:** Jobs are enabled with a valid schedule, but expected runs are not appearing.

**Solutions:**
1. **Is the app running?** The scheduler only runs while OpenHelm is open
2. **Was your Mac awake?** OpenHelm cannot wake a sleeping Mac, ensure your machine was on at the scheduled time
3. **Check the job's next fire time** in the job detail view, if it's in the past, the scheduler will pick it up within 60 seconds
4. **Verify the job is enabled**, the toggle on the job card must be on

## Run Stuck in "Running" State

**Symptom:** A run shows as running but there is no new log output and it appears frozen.

**Solutions:**
1. Wait up to 10 minutes, Claude Code may be silently processing or making API calls
2. If still stuck after 10 minutes, cancel the run from the run detail view
3. If the app was force-quit while a run was active, OpenHelm automatically marks orphaned running runs as failed on the next launch

## Job Always Fails

**Solutions:**
1. Check the run logs for the specific error message
2. Ensure Claude Code can access the project directory, the path must exist and be readable
3. Use **Open in Terminal** on a completed run to resume the Claude Code session and inspect what happened interactively
4. Add a **Correction note** to the job with specific guidance for recovering from the failure

## App Won't Open (Security Warning)

**Solution:**
1. Right-click OpenHelm in Applications and choose **Open** (bypasses Gatekeeper on first launch)
2. If still blocked: System Settings → Privacy & Security → scroll to the Security section → click **Open Anyway**

## Getting Help

- [Contact us](/contact), bug reports, feature requests, and support questions
- [Discord community](https://discord.gg/openhelm), community support and questions