> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/session-management/automations.md).

# Automations

Schedule recurring AI tasks in Nimbalyst. Automations run on a timer from a markdown file to produce standups, weekly reports, and reviews.

Automations are recurring AI tasks that run on a schedule inside Nimbalyst. Use them for anything you would otherwise do by hand on a rhythm: a daily standup summary, a weekly status report, a periodic code review.

Each automation is a markdown file in `nimbalyst-local/automations/`. The frontmatter defines the schedule and output settings, and the markdown body is the prompt that runs on each execution.

The [automations feature page](https://nimbalyst.com/features/automations/) covers scheduling patterns teams use, such as standups and recurring reviews.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FMfjzjXV1FnGKLbImxQbQ%2Fimage.png?alt=media&amp;token=86fd6966-4292-4962-b6aa-e7a260cdae82" alt="An automation file open in the editor, with a header bar showing Status Active, Schedule Daily at 09:00, last run date, run count, and a Run button"><figcaption><p>An open automation file. The header bar shows its status, schedule, last run, and run count above the prompt.</p></figcaption></figure>

## Creating an Automation

### Quick: Use `/automation`

Type `/automation` followed by a description:

```
/automation summarize my git commits every weekday morning
```

Nimbalyst creates the automation file with the right schedule and prompt, sets it to disabled so you can review it first, then tells you to open the file and enable it.

### Manual: Create the File

Create a `.md` file in `nimbalyst-local/automations/` with this format:

```markdown
---
automationStatus:
  id: standup-summary
  title: Daily Standup Summary
  enabled: false
  schedule:
    type: weekly
    days: [mon, tue, wed, thu, fri]
    time: "09:25"
  output:
    mode: new-file
    location: nimbalyst-local/automations/standup-summary/
    fileNameTemplate: "{{date}}-standup.md"
  runCount: 0
---

# Daily Standup Summary

Review the git log and recent file changes in this workspace since the previous business day. Summarize:

1. **What was accomplished** - List completed work based on commits and file changes
2. **What's in progress** - Identify files with uncommitted changes or recent branches
3. **Any blockers** - Note any error logs, failing tests, or stale branches

Format as a concise standup update suitable for sharing with the team.
```

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FIYQU8kxR0QI2fRzrqx3R%2Fimage.png?alt=media&amp;token=14e321d2-723e-4104-9c11-40390db93f3e" alt="The file tree showing an automations folder under nimbalyst-local, containing a daily-github-build-summary.md file and its output folder"><figcaption><p>Automation files live under nimbalyst-local/automations/, next to their output folders.</p></figcaption></figure>

## Document Header Controls

When you open an automation file, a header bar appears at the top of the editor with:

* **Enable/Disable toggle**: turn the automation on or off
* **Schedule display**: shows the schedule in plain language (for example, "Weekdays at 9:25 AM")
* **Last run info**: when it last ran and whether it succeeded
* **Run Now button**: trigger the automation immediately without waiting for the next scheduled time

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FMfjzjXV1FnGKLbImxQbQ%2Fimage.png?alt=media&amp;token=86fd6966-4292-4962-b6aa-e7a260cdae82" alt="The automation header bar with an enable toggle, Daily, Weekly, and Interval schedule tabs, a time picker, model selector, run history, and Run button"><figcaption><p>The header bar includes the enable toggle, schedule controls, a model selector, run history, and a Run button.</p></figcaption></figure>

## Schedule Types

### Daily

Runs once per day at the specified time.

```yaml
schedule:
  type: daily
  time: "09:00"
```

### Weekly

Runs on specific days of the week at the specified time. Valid days: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.

```yaml
schedule:
  type: weekly
  days: [mon, wed, fri]
  time: "14:00"
```

### Interval

Runs every N minutes while Nimbalyst is open.

```yaml
schedule:
  type: interval
  intervalMinutes: 60
```

## Output Modes

Each run's output is written to files. You control how with the `output` block:

| Mode         | Behavior                                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| **new-file** | Creates a new file per run. Use `fileNameTemplate` with `{{date}}`, `{{time}}`, and `{{id}}` placeholders. |
| **append**   | Appends each run's output to a single `output.md` file with date headers.                                  |
| **replace**  | Overwrites a single `output.md` file each run, so only the latest result is kept.                          |

**Example output config:**

```yaml
output:
  mode: new-file
  location: nimbalyst-local/automations/standup-summary/
  fileNameTemplate: "{{date}}-output.md"
```

## AI Provider

By default, automations run using Claude Code. You can optionally specify a different provider or model:

```yaml
provider: claude-code     # "claude-code", "claude", "openai", or "openai-codex"
model: claude-code:sonnet # optional: specific model ID
```

## Execution History

Each automation tracks its run history in a `history.json` file inside the output directory. This includes timestamps, duration, success or error status, and links to the AI session that produced the output.

You can also ask the agent in chat:

```
What's the run history for my standup-summary automation?
```

## Example: Weekly Project Status Report

```markdown
---
automationStatus:
  id: weekly-status
  title: Weekly Project Status
  enabled: true
  schedule:
    type: weekly
    days: [fri]
    time: "16:00"
  output:
    mode: new-file
    location: nimbalyst-local/automations/weekly-status/
    fileNameTemplate: "{{date}}-status.md"
  runCount: 0
---

# Weekly Project Status

Generate a weekly status report for this project:

1. **Summary** - One paragraph overview of the week's progress
2. **Completed** - List all merged PRs and completed features this week (check git log)
3. **In Progress** - List open branches and their status
4. **Metrics** - Count commits, files changed, and lines added/removed
5. **Next Week** - Based on open branches and TODOs, suggest priorities

Format as a clean markdown report.
```

## Frontmatter Fields Reference

| Field                      | Required         | Description                                                     |
| -------------------------- | ---------------- | --------------------------------------------------------------- |
| `id`                       | Yes              | Unique kebab-case identifier                                    |
| `title`                    | Yes              | Human-readable name                                             |
| `enabled`                  | Yes              | `true` or `false`                                               |
| `schedule.type`            | Yes              | `daily`, `weekly`, or `interval`                                |
| `schedule.time`            | For daily/weekly | Time in 24h format (`"HH:MM"`)                                  |
| `schedule.days`            | For weekly       | Array of day abbreviations                                      |
| `schedule.intervalMinutes` | For interval     | Number of minutes between runs                                  |
| `output.mode`              | Yes              | `new-file`, `append`, or `replace`                              |
| `output.location`          | Yes              | Path for output files (relative to workspace)                   |
| `output.fileNameTemplate`  | For new-file     | Filename with `{{date}}`, `{{time}}`, and `{{id}}` placeholders |
| `provider`                 | No               | AI provider to use                                              |
| `model`                    | No               | Specific model ID                                               |
| `runCount`                 | Auto             | Incremented on each run                                         |
| `lastRun`                  | Auto             | ISO timestamp of last execution                                 |
| `lastRunStatus`            | Auto             | `success` or `error`                                            |
| `nextRun`                  | Auto             | ISO timestamp of next scheduled run                             |

## Tips

* **Start disabled**: new automations default to `enabled: false`. Review the prompt and schedule before enabling.
* **Edit anytime**: just edit the markdown file. Changes are picked up within 30 seconds.
* **Run Now to test**: use the Run Now button in the document header to test your automation before relying on the schedule.
* **Check output**: outputs appear in the `location` directory. Open them from the file tree.
* **Automations only run while Nimbalyst is open**: if Nimbalyst is closed at the scheduled time, the automation does not fire retroactively.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimbalyst.com/session-management/automations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.