---
url: /overseer/commands.md
description: >-
  Complete reference for all overseer commands — global flags, output formats,
  and an index of every available command.
---

# Commands

Full reference for all overseer subcommands.

## Global flags

| Flag | Default | Description |
|---|---|---|
| `--format` | `text` | Output format: `text` or `json` |
| `--version` | — | Print overseer version and exit |
| `--help` | — | Print help for any command |

All commands that produce structured data support `--format json`. JSON output always emits an empty array `[]` rather than `null` when there are no items.

## Command index

| Command | Description |
|---|---|
| [`accounts`](/commands/accounts) | List 1Password accounts signed into the `op` CLI |
| [`brain`](/commands/brain) | Manage the brain directory |
| [`brew`](/commands/brew) | Manage Homebrew packages via Brewfile |
| [`completion`](/commands/completion) | Generate shell completion scripts |
| [`config`](/commands/config) | Show active config and JSON Schema |
| [`context`](/commands/context) | Print a self-contained AI-friendly description of overseer |
| [`daily`](/commands/daily) | Morning briefing: Jira, Slack, Calendar, PRs |
| [`env`](/commands/env) | Manage environment variable profiles |
| [`focus`](/commands/focus) | Timed focus session with optional Jira time logging |
| [`git`](/commands/git) | Git identity management |
| [`init`](/commands/init) | Create `~/.config/overseer/config.local.yaml` interactively |
| [`mcp`](/commands/mcp) | Start MCP server for AI assistant integration |
| [`note`](/commands/note) | Obsidian vault integration |
| [`notify`](/commands/notify) | Fire a native OS desktop notification |
| [`plugins`](/commands/plugins) | List and toggle native plugins |
| [`prs`](/commands/prs) | Open PRs across GitHub and GitLab |
| [`repos`](/commands/repos) | Manage and sync git repos |
| [`run`](/commands/run) | Run a command with secrets injected |
| [`setup`](/commands/setup) | Interactive bootstrap wizard |
| [`ssh`](/commands/ssh) | Manage SSH config profiles |
| [`standup`](/commands/standup) | Synthesize yesterday's activity into a standup message |
| [`status`](/commands/status) | Health-check all integrations |
| [`update`](/commands/update) | Self-update the binary |
| [`weekly`](/commands/weekly) | Activity summary for the past 7 days |

---

---
url: /overseer/commands/accounts.md
---
# accounts

List all 1Password accounts signed into the `op` CLI.

```bash
overseer accounts
overseer accounts --format json
```

Shows the account URL, email address, and USER UUID. The UUID is what you set as `op_account` in config fields that reference a specific 1Password account.

## JSON output

```json
[
  {
    "url": "my.1password.com",
    "email": "you@example.com",
    "user_uuid": "he7em6mxcdlsewgnzrqldjizi"
  }
]
```

---

---
url: /overseer/commands/brain.md
---
# brain

Manage the brain directory. See [Concepts → Brain](/concepts/brain) for what the brain is.

## Subcommands

### `overseer brain init`

Clone the brain repo from `brain.url` in config. Use this on a fresh machine to pull down your existing brain.

```bash
overseer brain init
```

### `overseer brain setup`

Pull the latest brain changes and re-apply config: symlinks dotfiles, installs Brew packages, and applies git profiles. Equivalent to running the relevant parts of the setup wizard without the interactive prompts.

```bash
overseer brain setup
overseer brain setup --dry-run   # preview without making changes
```

### `overseer brain pull`

Run `git pull` in the brain directory.

```bash
overseer brain pull
```

### `overseer brain push`

Run `git push` in the brain directory.

```bash
overseer brain push
```

### `overseer brain git-init`

Initialise a new git repo in an existing brain directory. Use this when setting up a brain for the first time without an existing remote.

```bash
overseer brain git-init
```

### `overseer brain status`

Show brain directory health: git status, last commit, and whether dotfile symlinks are in place.

```bash
overseer brain status
```

### `overseer brain path`

Print the resolved brain path. Useful for scripts that need to reference the brain directory.

```bash
overseer brain path
# → /Users/you/brain
```

---

---
url: /overseer/commands/brew.md
---
# brew

Manage Homebrew packages via a Brewfile in your brain.

The Brewfile path is configured via `brew.brewfile` in `config.yaml` (relative to `system.repos_path`). Defaults to `overseer/Brewfile` inside your repos directory.

## Subcommands

### `overseer brew check`

Show packages listed in the Brewfile that are not yet installed on this machine.

```bash
overseer brew check
```

### `overseer brew install`

Run `brew bundle` to install all packages from the Brewfile.

```bash
overseer brew install
```

### `overseer brew dump`

Update the Brewfile from currently installed packages (`brew bundle dump --force`).

```bash
overseer brew dump
```

---

---
url: /overseer/commands/completion.md
---
# completion

Generate shell completion scripts for overseer.

## Zsh

```bash
# Source in current session
source <(overseer completion zsh)

# Persist across sessions
echo 'source <(overseer completion zsh)' >> ~/.zshrc
```

## Bash

```bash
echo 'source <(overseer completion bash)' >> ~/.bashrc
```

## Fish

```bash
overseer completion fish > ~/.config/fish/completions/overseer.fish
```

## PowerShell

```bash
overseer completion powershell
```

---

---
url: /overseer/commands/config.md
---
# config

Show the active merged configuration and related utilities.

## Usage

```bash
overseer config                   # human-readable summary
overseer config --format json     # full merged config as JSON
overseer config schema            # print the JSON Schema for config.yaml
```

The displayed config is the result of merging `brain/overseer/config.yaml` with `~/.config/overseer/config.local.yaml`. Local values take precedence.

Secret values (fields containing `op://` references) are shown as their reference strings, never as resolved plaintext.

## JSON Schema

`overseer config schema` prints the full JSON Schema for `config.yaml`. You can use this to enable inline validation and autocomplete in editors that support YAML Language Server:

```yaml [brain/overseer/config.yaml]
# yaml-language-server: $schema=https://arthurvasconcelos.github.io/overseer/schema.json
```

See [Concepts → Config](/concepts/config) for all config keys.

---

---
url: /overseer/commands/context.md
---
# context

Print a self-contained description of overseer for use in AI assistant chats.

```bash
overseer context
overseer context --format json
```

## Text output

Generates a comprehensive markdown document describing all commands, flags, config structure, and key concepts. Designed to be pasted directly into an AI chat as context.

```bash
# Copy to clipboard (macOS)
overseer context | pbcopy

# Save to a file
overseer context > overseer-context.md
```

## JSON output

Returns a structured command manifest with the tool name, version, description, and a full tree of commands with their flags and subcommands.

```json
{
  "tool": "overseer",
  "version": "1.2.3",
  "description": "...",
  "brain": "...",
  "commands": [
    {
      "path": "overseer brain",
      "short": "Manage the brain directory",
      "subcommands": [...]
    }
  ]
}
```

## MCP alternative

For persistent AI integration rather than a one-off paste, see [`overseer mcp`](/commands/mcp).

---

---
url: /overseer/commands/daily.md
description: >-
  Run your morning briefing — pull open PRs, Jira tickets, calendar events, and
  Slack highlights into a single digest.
---

# daily

Morning briefing: fetches and displays today's Jira tickets, Slack mentions, Google Calendar events — all in parallel.

```bash
overseer daily
```

Sections are contributed by **enabled native plugins**. Each plugin runs in its own goroutine and results are printed in a deterministic order. Integrations that are not enabled are silently skipped.

Built-in plugins that contribute to `daily`:

| Plugin | Config key | What it shows |
|---|---|---|
| `jira` | `integrations.jira[]` | Open issues assigned to you |
| `slack` | `integrations.slack[]` | Recent mentions |
| `google` | `integrations.google[]` | Today's calendar events |

External plugins can also contribute a section by declaring `"hooks": ["daily"]` in their [sidecar manifest](/plugins/) and handling the `daily` argument when called.

---

---
url: /overseer/commands/env.md
---
# env

Manage environment variable profiles. Profiles map a name to a 1Password secret environment, which injects a set of environment variables into the current shell.

```bash
overseer env list            # list all configured profiles
overseer env show <name>     # print the variables in a profile (values redacted)
eval $(overseer env use <name>)   # apply a profile to the current shell
```

## Config

Profiles are defined in `config.yaml` under `secrets.environments`:

```yaml
secrets:
  environments:
    work: h4e7em6mxcdlsewgnzrqldjizi    # 1Password secret environment ID
    personal: ab1cd2ef3gh4ij5kl6mn7op8
```

The environment ID is the 1Password secret environment identifier. Run `op env list` to find your environment IDs.

## Applying a profile

`overseer env use` prints `export KEY=VALUE` lines to stdout. Use `eval` to apply them in the current shell session:

```bash
eval $(overseer env use work)
```

Variables are resolved from 1Password at the time of the `use` command. They are not stored in any file.

---

---
url: /overseer/commands/focus.md
---
# focus

Start a timed focus session. Shows a live countdown in the terminal. Sends a desktop notification when the session ends. Optionally logs the elapsed time as a Jira worklog.

```bash
overseer focus              # 25-minute session (default)
overseer focus 45m          # 45-minute session
overseer focus 1h30m        # 90-minute session
overseer focus 90           # plain number = minutes
```

Duration formats accepted: `25m`, `1h`, `1h30m`, `90` (minutes).

## Jira time logging

Pass `--issue` to log the elapsed time to a Jira issue when the session ends. You will be prompted to confirm before the worklog is submitted.

```bash
overseer focus --issue PROJECT-123
overseer focus --issue PROJECT-123 --instance work   # pick a specific Jira instance
overseer focus 45m --issue PROJECT-123 --name "API design"
```

| Flag | Description |
|---|---|
| `--issue` | Jira issue key to log time against |
| `--name` | Label for the session (shown in the terminal header) |
| `--instance` | Jira instance name from config (defaults to first configured) |

If you stop the session early with `ctrl+c`, the elapsed time (minimum 1 minute) is used for the worklog prompt.

---

---
url: /overseer/commands/git.md
description: >-
  Manage git identity profiles — configure per-repo user name, email, and GPG
  signing key from a central config.
---

# git

Git identity management. Define named profiles with different email addresses, signing keys, and git settings, then apply them per-repo or globally.

## `overseer git setup`

Interactive profile picker. Presents all configured profiles and applies the selected one to the current repo (or globally with `--global`).

```bash
overseer git setup
overseer git setup --global
```

## `overseer git profile`

Manage git profiles.

### list

```bash
overseer git profile list
overseer git profile list --format json
```

JSON output: array of profile objects.

```json
[
  {
    "name": "personal",
    "email": "you@personal.com",
    "signing_key": "op://Personal/SSH Key/public key",
    "user_name": "Arthur Vasconcelos",
    "gpg_format": "ssh",
    "gpg_ssh_program": "/Applications/1Password.app/Contents/MacOS/op-ssh-sign",
    "commit_gpgsign": true,
    "op_account": ""
  }
]
```

### add

Interactively create a new git profile and save it to config.

```bash
overseer git profile add
```

### edit

Edit an existing profile.

```bash
overseer git profile edit personal
overseer git profile edit          # interactive picker
```

### remove

Remove a profile from config.

```bash
overseer git profile remove personal
```

### apply

Apply a profile to the current repo (or globally).

```bash
overseer git profile apply personal
overseer git profile apply personal --global
```

This sets `user.email`, `user.name`, `user.signingKey`, `gpg.format`, `gpg.ssh.program`, and `commit.gpgSign` in `.git/config` (or `~/.gitconfig` with `--global`).

### defaults

View and edit shared git defaults that are merged into every profile.

```bash
overseer git profile defaults
```

## Config

Profiles are stored in `git.profiles[]` and shared defaults in `git.defaults`. See [Concepts → Config](/concepts/config#git) for the full schema.

---

---
url: /overseer/commands/init.md
---
# init

Interactive wizard that creates `~/.config/overseer/config.local.yaml` — the machine-local config file.

```bash
overseer init
```

Walks through machine-specific settings: repos path, brain path override, and any values that should not live in the shared brain config. Safe to re-run; existing values are shown as defaults.

`config.local.yaml` is never committed to the brain repo. It holds machine-specific paths and any tokens you prefer to keep out of version control entirely (though using `op://` references in the brain config is the preferred approach for secrets).

---

---
url: /overseer/commands/mcp.md
---
# mcp

Start a local [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, letting AI assistants connect to overseer's data and run commands.

```bash
overseer mcp
```

## Setup with Claude

Add overseer as an MCP server in `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "overseer": {
      "command": "overseer",
      "args": ["mcp"]
    }
  }
}
```

## Available MCP tools

| Tool | Description |
|---|---|
| `list_commands` | List all overseer commands with descriptions |
| `run_prs` | Fetch open PRs and MRs from configured GitHub/GitLab instances |
| `run_repos_status` | Show git status for all managed repos |
| `get_config` | Return the active config as JSON |
| `run_command` | Run a shell command with secrets injected |
| `run_note_search` | Search the Obsidian vault |

### `run_command` parameters

| Parameter | Required | Description |
|---|---|---|
| `command` | Yes | Shell command to run (executed via `sh -c`) |
| `gitlab` | No | GitLab instance name — injects `GITLAB_TOKEN` and `GITLAB_HOST` |
| `github` | No | GitHub instance name — injects `GITHUB_TOKEN` |
| `env` | No | 1Password environment name — injects its secrets as env vars |

## Alternative: context dump

For a one-off paste into an AI chat rather than persistent integration, use [`overseer context`](/commands/context).

---

---
url: /overseer/commands/note.md
---
# note

Obsidian vault integration. Requires `obsidian.vault_path` and `obsidian.vault_name` in config.

## Subcommands

### `overseer note daily`

Open or create today's daily note in Obsidian. Uses the configured `obsidian.daily_notes_folder`. If the note doesn't exist, it is created from the configured daily template.

```bash
overseer note daily
```

### `overseer note new`

Create a new note. Presents an interactive folder and template picker, then opens the new note in Obsidian.

```bash
overseer note new
overseer note new "Meeting notes"   # skip the title prompt
```

### `overseer note search`

Search all markdown files in the vault for a query string. Returns matching lines with file path and line number.

```bash
overseer note search kubernetes
overseer note search kubernetes --format json
```

JSON output:

```json
[
  {
    "file": "Daily/2025-04-10.md",
    "line_num": 12,
    "line": "- Kubernetes context switching with kubectx"
  }
]
```

## Config

| Key | Description |
|---|---|
| `obsidian.vault_path` | Absolute path to the vault |
| `obsidian.vault_name` | Vault name as registered in Obsidian |
| `obsidian.daily_notes_folder` | Folder for daily notes |
| `obsidian.templates_folder` | Folder for note templates |
| `obsidian.default_folder` | Default folder for `note new` |

---

---
url: /overseer/commands/notify.md
---
# notify

Fire a native OS desktop notification.

```bash
overseer notify "Title" "Body text"
```

Uses the system notification API on macOS (`osascript`) and Linux (`notify-send`). Primarily intended for use inside brain scripts and external plugins that want to alert you when a long-running operation completes.

```bash
# Example: notify when a build finishes
make build && overseer notify "Build done" "Release build succeeded"
```

---

---
url: /overseer/commands/plugins.md
---
# plugins

List available native and external plugins.

```bash
overseer plugins
```

Shows all native plugins with their enabled/disabled state, then any external plugins discovered on PATH or in `brain/overseer/plugins/`.

```
▸ native plugins
  jira       ✓ enabled   Jira issue tracking
  slack      ✓ enabled   Slack mentions
  google     ✓ enabled   Google Calendar events
  obsidian   ✓ enabled   Obsidian vault
  github     ✓ enabled   GitHub pull requests
  gitlab     ✓ enabled   GitLab merge requests
  claude     ✗ disabled  Claude AI config management

▸ external plugins
  deploy     Deploy to production
```

See [Plugins](/plugins/) for how to enable, disable, and author plugins.

---

---
url: /overseer/commands/prs.md
---
# prs

List open pull requests (GitHub) and merge requests (GitLab) across all configured instances.

```bash
overseer prs
overseer prs --format json
```

Fetches from all configured `integrations.github[]` and `integrations.gitlab[]` instances in parallel.

## JSON output

```json
[
  {
    "source": "github",
    "instance": "personal",
    "items": [
      {
        "number": 42,
        "title": "Add dark mode",
        "repo": "you/myproject",
        "url": "https://github.com/you/myproject/pull/42",
        "draft": false
      }
    ]
  },
  {
    "source": "gitlab",
    "instance": "work",
    "items": [
      {
        "iid": 5,
        "title": "Fix auth middleware",
        "project": "team/api",
        "url": "https://gitlab.company.com/team/api/-/merge_requests/5",
        "draft": false,
        "status": "can_be_merged"
      }
    ]
  }
]
```

---

---
url: /overseer/commands/repos.md
description: >-
  Manage your registered git repositories — check status across all repos, pull
  updates, and run setup scripts in bulk.
---

# repos

Manage git repositories defined in the `repos[]` section of config.

## Subcommands

### `overseer repos status`

Show git status across all managed repos: branch, clean/dirty, and list of changed files.

```bash
overseer repos status
overseer repos status --format json
```

JSON output:

```json
[
  {
    "name": "brain",
    "path": "/Users/you/brain",
    "readonly": false,
    "cloned": true,
    "branch": "main",
    "clean": true,
    "changes": []
  },
  {
    "name": "work-api",
    "path": "/Users/you/repos/work/api",
    "readonly": false,
    "cloned": true,
    "branch": "feature/auth",
    "clean": false,
    "changes": ["M src/auth.go", "?? src/auth_test.go"]
  }
]
```

### `overseer repos pull`

Pull (or clone if missing) all managed repos. Repos with `readonly: true` are skipped.

```bash
overseer repos pull
```

### `overseer repos setup`

Apply the configured git profile to each already-cloned repo. Useful after adding a new profile or changing which profile a repo should use.

```bash
overseer repos setup
```

## Config

Repos are defined in `repos[]` in config. See [Concepts → Config](/concepts/config#repos) for all fields.

---

---
url: /overseer/commands/run.md
---
# run

Run a command with secrets resolved and injected as environment variables.

```bash
overseer run [flags] -- <cmd> [args...]
```

## Flags

| Flag | Description |
|---|---|
| `--gitlab <name>` | GitLab instance name from config — injects `GITLAB_TOKEN` and `GITLAB_HOST` |
| `--github <name>` | GitHub instance name from config — injects `GITHUB_TOKEN` |
| `--env <name>` | 1Password environment alias or account ID — injects all secrets; mutually exclusive with `--gitlab`/`--github` |

## Examples

```bash
# Authenticated curl against a configured GitLab instance
overseer run --gitlab work -- curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  https://$GITLAB_HOST/api/v4/projects

# gh CLI with a configured GitHub token
overseer run --github personal -- gh repo list

# Run a Makefile target with a 1Password environment's secrets
overseer run --env p24 -- make deploy

# Use a raw 1Password account ID instead of an alias
overseer run --env he7em6mxcdlsewgnzrqldjizi -- make deploy
```

## How it works

* `--gitlab <name>` looks up the matching entry in `integrations.gitlab[]`, resolves its token via `op read`, and exports `GITLAB_TOKEN` and `GITLAB_HOST` before running the command.
* `--github <name>` does the same for `integrations.github[]`, exporting `GITHUB_TOKEN`.
* `--env <name>` resolves the alias through `secrets.environments` to a 1Password account ID, then uses `op run` to inject all secrets from that account.

See [Concepts → Secrets](/concepts/secrets) for how secret resolution works.

---

---
url: /overseer/commands/setup.md
---
# setup

Interactive bootstrap wizard for a new machine. Walks through everything in one session: brain path, git remote, machine settings, directory scaffolding, dotfile wiring, and Brew packages.

```bash
overseer setup
overseer setup --dry-run   # preview without making changes
```

Safe to re-run at any time — existing values are shown as defaults and nothing is overwritten without your input.

## What it does

1. Resolves (or prompts for) the brain path
2. Clones the brain repo if a remote is configured and the brain isn't present
3. Applies dotfile symlinks from `brain/overseer/dotfiles/`
4. Runs `brew bundle` from the Brewfile
5. Applies git profiles to managed repos

To re-apply config without the interactive wizard, use [`overseer brain setup`](/commands/brain#overseer-brain-setup).

---

---
url: /overseer/commands/ssh.md
---
# ssh

Manage SSH config profiles. Profiles are named SSH config blocks stored in the brain. Activating a profile writes it to `~/.ssh/overseer_active.conf`, which is included by `~/.ssh/config` via an overseer-managed `Include` directive.

```bash
overseer ssh list            # list all profiles
overseer ssh show <name>     # print the SSH config block for a profile
overseer ssh use <name>      # activate a profile
overseer ssh setup           # add the Include directive to ~/.ssh/config (one-time setup)
```

## First-time setup

Run `overseer ssh setup` once to add the overseer `Include` directive to `~/.ssh/config`. This is idempotent — safe to run again.

```bash
overseer ssh setup
```

After that, switching profiles is a single command:

```bash
overseer ssh use work       # activates the "work" SSH profile
overseer ssh use personal   # switches to the "personal" profile
```

## Config

SSH profiles are stored in the brain under `overseer/ssh/`. Each file is a standard SSH config block named `<profile>.conf`:

```[brain/overseer/ssh/work.conf]
Host github.com
  IdentityFile ~/.ssh/id_work
  User git
```

---

---
url: /overseer/commands/standup.md
---
# standup

Synthesize yesterday's activity into a standup message. Pulls Jira issues updated yesterday, GitLab MRs, and GitHub PRs from all configured instances, then uses Claude to generate a concise standup summary.

```bash
overseer standup
overseer standup --post   # post the summary to Slack after generating
```

The generated text is printed to the terminal. With `--post` it is also sent to the Slack channel configured under `standup.channel` in `config.yaml`.

## What it aggregates

* **Jira** — issues where you are the assignee, updated in the last 24 hours
* **GitHub** — PRs you opened or reviewed yesterday
* **GitLab** — MRs you authored or reviewed yesterday

Results are passed to Claude (via the configured Claude API key) to produce a short, human-readable standup. If no Claude key is configured the raw list is printed instead.

---

---
url: /overseer/commands/status.md
---
# status

Health-check all configured integrations.

```bash
overseer status
overseer status --format json
```

Checks are contributed by **enabled native plugins** (and external plugins that declare `"hooks": ["status"]`). Each check runs in its own goroutine. Always includes a 1Password check regardless of plugin state.

Built-in plugins that contribute to `status`:

| Plugin | Checks |
|---|---|
| `jira` | Auth ping per configured instance |
| `slack` | Auth ping per configured workspace |
| `google` | OAuth token validity per account |
| `obsidian` | Vault path exists on disk |
| `claude` | Symlink health for managed Claude config files |

## JSON output

```json
[
  { "name": "1password", "ok": true, "message": "signed in (2 accounts)" },
  { "name": "jira/work", "ok": true, "message": "you@company.com" },
  { "name": "slack/work", "ok": true, "message": "@username" },
  { "name": "google/personal", "ok": false, "message": "token expired — run: overseer daily to refresh" },
  { "name": "claude", "ok": true, "message": "all links healthy (6 targets)" }
]
```

Useful for a quick sanity check after setting up a new machine or rotating credentials.

---

---
url: /overseer/commands/update.md
---
# update

Check for and apply a new overseer release.

```bash
overseer update
```

Fetches the latest release from GitHub, compares it against the running version, and replaces the binary if a newer version is available.

If you installed via Homebrew, prefer `brew upgrade arthurvasconcelos/tap/overseer` instead.

---

---
url: /overseer/commands/weekly.md
---
# weekly

Activity summary for the past 7 days. Aggregates Jira issues, GitHub PRs, and GitLab MRs from all configured instances and prints them grouped by source.

```bash
overseer weekly
overseer weekly --ai      # generate an AI-written narrative using Claude
```

## What it aggregates

* **Jira** — issues assigned to you, updated in the last 7 days
* **GitHub** — PRs you opened or reviewed in the last 7 days
* **GitLab** — MRs you authored or reviewed in the last 7 days

All sources run in parallel. Missing or unconfigured integrations are skipped silently.

## AI summary

With `--ai`, the aggregated data is sent to Claude to produce a short narrative suitable for a weekly status update or engineering report. Requires a Claude API key configured under `claude.api_key` in `config.yaml`.

---

---
url: /overseer/concepts.md
---
# Concepts

Key ideas behind how overseer is structured and how it handles configuration.

* [Brain](/concepts/brain) — Your private config repo — the single source of truth for your personal setup.
* [Config](/concepts/config) — Two-layer merge, all config keys, and the JSON Schema.
* [Secrets](/concepts/secrets) — 1Password `op://` references resolved at runtime.

---

---
url: /overseer/concepts/brain.md
description: >-
  The brain is a private git repo that holds your overseer config, dotfiles, and
  personal data — separate from the tool itself.
---

# Brain

The **brain** is a private git repo that holds your personal config. It is intentionally separate from the overseer binary — your config can be version-controlled, backed up, and shared across machines without touching the tool itself.

## Structure

```
brain/
  overseer/
    config.yaml          # integrations, git profiles, repos, etc.
    Brewfile             # Homebrew packages
    Brewfile.local       # machine-specific packages (gitignored)
    dotfiles/            # mirrors ~/ — symlinked by overseer brain setup
      .zshrc             → ~/.zshrc
      .gitconfig         → ~/.gitconfig
      .config/
        starship.toml    → ~/.config/starship.toml
    plugins/             # overseer-* plugin executables
```

See [brain-example/](https://github.com/arthurvasconcelos/overseer/tree/main/brain-example) in the repo for a fully commented example layout.

## Path resolution

overseer finds your brain in this order:

1. `OVERSEER_BRAIN` environment variable
2. `system.brain_path` in `~/.config/overseer/config.local.yaml`
3. `brain.path` in `brain/overseer/config.yaml`
4. `~/brain` (default)

Print the resolved path at any time:

```bash
overseer brain path
```

## Referenced paths

Not everything overseer uses lives in the brain. Some directories are **referenced by path** in `config.yaml` and can stay wherever they already are:

| Config key | What it points to |
|---|---|
| `obsidian.vault_path` | Your Obsidian vault |
| `system.repos_path` (local) | Where managed repos are cloned |

These are typically machine-specific and belong in `config.local.yaml`, not the shared brain config.

## Brain commands

| Command | Description |
|---|---|
| `overseer brain init` | Clone the brain repo from `brain.url` |
| `overseer brain setup` | Pull latest changes and re-apply config |
| `overseer brain status` | Show brain git status and health |
| `overseer brain pull` | `git pull` the brain repo |
| `overseer brain push` | `git push` the brain repo |
| `overseer brain git-init` | Initialise a new git repo in an existing brain directory |
| `overseer brain path` | Print the resolved brain path |

---

---
url: /overseer/concepts/config.md
description: >-
  How overseer's two-layer config system works — brain config merged with local
  overrides, covering integrations, git profiles, and repos.
---

# Config

## Two config files

overseer merges two config files on every run. The local file always takes precedence:

| File | Purpose |
|---|---|
| `brain/overseer/config.yaml` | Shared, portable, committed to your brain repo |
| `~/.config/overseer/config.local.yaml` | Machine-local overrides — tokens, paths, never committed |

Inspect the merged result at any time:

```bash
overseer config           # human-readable summary
overseer config --format json  # full config as JSON
```

## JSON Schema

The full JSON Schema for `config.yaml` is available via:

```bash
overseer config schema
```

You can also point your editor at the schema for inline validation and autocomplete:

```yaml [brain/overseer/config.yaml]
# yaml-language-server: $schema=https://arthurvasconcelos.github.io/overseer/schema.json
```

## Config keys

### `secrets`

```yaml
secrets:
  environments:
    p24: "he7em6mxcdlsewgnzrqldjizi"  # alias → 1Password account ID
```

| Key | Description |
|---|---|
| `secrets.environments` | Map of alias → 1Password account ID. Used with `overseer run --env <alias>`. |

***

### `integrations`

```yaml
integrations:
  jira:
    - name: work
      base_url: https://company.atlassian.net
      email: you@company.com
      token: "op://Work/Jira/token"
      op_account: work
  slack:
    - name: work
      token: "op://Work/Slack Bot Token/token"
      user_token: "op://Work/Slack User Token/token"
      group_handles:
        - backend-team
        - frontend-team
  google:
    - name: personal
      credentials_doc: "op://Personal/Google/credentials_json"
  github:
    - name: personal
      token: "op://Personal/GitHub/token"
  gitlab:
    - name: work
      base_url: https://gitlab.company.com
      token: "op://Work/GitLab/token"
```

| Key | Fields |
|---|---|
| `integrations.jira[]` | `name`, `base_url`, `email`, `token`, `op_account` |
| `integrations.slack[]` | `name`, `token`, `op_account`, `user_token` (optional, for search), `group_handles` (optional, usergroup handles to watch) |
| `integrations.google[]` | `name`, `credentials_doc`, `op_account` — run `overseer gcal auth` once per account to cache the OAuth token |
| `integrations.github[]` | `name`, `token`, `op_account` |
| `integrations.gitlab[]` | `name`, `base_url`, `token`, `op_account` |

***

### `git`

```yaml
git:
  defaults:
    user_name: Arthur Vasconcelos
    gpg_format: ssh
    gpg_ssh_program: /Applications/1Password.app/Contents/MacOS/op-ssh-sign
    commit_gpgsign: true
  profiles:
    - name: personal
      email: arthur@personal.com
      signing_key: "op://Personal/SSH Key/public key"
    - name: work
      email: arthur@company.com
      signing_key: "op://Work/SSH Key/public key"
      op_account: work
```

| Key | Description |
|---|---|
| `git.defaults` | Shared settings applied to all profiles unless overridden |
| `git.profiles[]` | Named git identities. Fields: `name`, `email`, `signing_key`, `user_name`, `gpg_format`, `gpg_ssh_program`, `commit_gpgsign`, `op_account` |

***

### `system` (machine-local)

```yaml
system:
  repos_path: ~/repos
  brain_path: ~/brain
```

| Key | Description |
|---|---|
| `system.repos_path` | Where managed repos are cloned |
| `system.brain_path` | Override brain directory path for this machine |

These belong in `config.local.yaml`, not the shared brain config.

***

### `brain`

```yaml
brain:
  path: ~/brain
  url: git@github.com:you/brain.git
  git_profile: personal
```

| Key | Description |
|---|---|
| `brain.path` | Canonical brain path (portable across machines) |
| `brain.url` | Git remote for cloning and pushing |
| `brain.git_profile` | Git profile to use for brain commits |

***

### `obsidian`

```yaml
obsidian:
  vault_path: ~/Documents/Notes
  vault_name: Notes
  daily_notes_folder: Daily
  templates_folder: Templates
  default_folder: Inbox
```

| Key | Description |
|---|---|
| `obsidian.vault_path` | Absolute path to your Obsidian vault |
| `obsidian.vault_name` | Vault name as registered in Obsidian |
| `obsidian.daily_notes_folder` | Folder for daily notes |
| `obsidian.templates_folder` | Folder for note templates |
| `obsidian.default_folder` | Default folder for new notes |

***

### `brew`

```yaml
brew:
  brewfile: overseer/Brewfile
```

| Key | Description |
|---|---|
| `brew.brewfile` | Brewfile path relative to `repos_path` |

***

### `repos`

```yaml
repos:
  - name: brain
    url: git@github.com:you/brain.git
    path: ~/brain
    git_profile: personal
  - name: work-api
    url: git@gitlab.company.com:team/api.git
    path: ~/repos/work/api
    git_profile: work
    readonly: false
```

| Field | Description |
|---|---|
| `name` | Display name |
| `url` | Git remote URL |
| `path` | Local path (absolute or `~`-prefixed) |
| `git_profile` | Git identity to apply |
| `readonly` | If `true`, `repos pull` skips this repo |

### `repo_dirs`

Directories to auto-discover git repositories from. Overseer recursively walks each listed directory and treats every subdirectory containing a `.git` folder as a repo root. The listed directory itself is excluded even if it has `.git`. Useful for large, externally-managed repo trees (e.g. a company workspace cloned by a plugin).

```yaml
repo_dirs:
  - ~/repos/p24          # all repos under this tree are picked up automatically
```

Used by: `overseer standup` (commit history).

---

---
url: /overseer/concepts/secrets.md
description: >-
  Reference secrets from 1Password using op:// URIs in your overseer config —
  resolved at runtime, never stored in plaintext.
---

# Secrets

overseer never stores secret values. Instead, config fields that accept secrets use **1Password URI references** that are resolved at runtime via the `op` CLI.

## Reference format

```
op://vault/item/field
```

Example:

```yaml
integrations:
  github:
    - name: personal
      token: "op://Personal/GitHub PAT/token"
```

When overseer reads this field, it calls `op read op://Personal/GitHub PAT/token` and substitutes the resolved value. The plaintext never touches the config file.

## The `op_account` field

If you have multiple 1Password accounts (e.g. personal and work), specify which account to use per integration:

```yaml
integrations:
  gitlab:
    - name: work
      token: "op://Work/GitLab/token"
      op_account: work
```

`op_account` maps to a 1Password account short name or UUID. Run the following to see your configured accounts and their IDs:

```bash
overseer accounts
```

## `secrets.environments`

Named environments let you inject all secrets from a 1Password account as environment variables for a subprocess:

```yaml
secrets:
  environments:
    p24: "he7em6mxcdlsewgnzrqldjizi"
```

Then use `overseer run --env p24 -- <command>` to run any command with those secrets injected. The alias `p24` maps to the 1Password account ID.

See [`overseer run`](/commands/run) for full usage.

---

---
url: /overseer/plugins.md
---
# Plugins

overseer supports two types of plugins: **native plugins** compiled into the binary, and **external plugins** discovered as executables on PATH or in the brain.

## Native plugins

Native plugins ship with the overseer binary and can be enabled or disabled via config. They integrate deeply with built-in commands (`daily`, `status`) through declared extension points.

See [Native plugins](/plugins/native) for the full reference.

## External plugins

Any executable named `overseer-<name>` is automatically registered as `overseer <name>` with no configuration required.

overseer searches for plugins in two places (in order):

1. `brain/overseer/plugins/` — your private brain plugins, not requiring PATH changes
2. Anywhere on `PATH`

The first match wins. Plugin executables can be written in any language.

### Naming

```
overseer-deploy   →   overseer deploy
overseer-standup  →   overseer standup
```

### Context injection

Before running a plugin, overseer injects an `OVERSEER_CONTEXT` environment variable containing a JSON payload with:

* `version` — the running overseer version
* `config_path` — path to the merged config file
* `secrets` — a map of resolved secrets declared in the sidecar manifest

### Sidecar manifest (optional)

Place `overseer-<name>.json` alongside the binary to declare metadata:

```json
{
  "description": "Deploy to production",
  "secrets": ["github.personal", "gitlab.work"],
  "hooks": ["daily", "status"]
}
```

| Field | Description |
|---|---|
| `description` | Shown in `overseer --help` and `overseer plugins` |
| `secrets` | Integration references whose tokens overseer resolves and injects via `OVERSEER_CONTEXT` |
| `hooks` | Extension points to participate in: `"daily"` and/or `"status"` |

#### `daily` hook

When `hooks` includes `"daily"`, overseer calls `overseer-<name> daily` during `overseer daily`. The plugin's stdout is printed as a section in the briefing output.

#### `status` hook

When `hooks` includes `"status"`, overseer calls `overseer-<name> status` during `overseer status`. The plugin must output a JSON array:

```json
[{ "name": "my-check", "ok": true, "message": "all good" }]
```

Each item is displayed as a status row alongside built-in checks.

## Listing plugins

```bash
overseer plugins
```

Shows all native plugins and their enabled/disabled state, followed by any discovered external plugins.

## SDKs

Plugin SDKs are available for Python and TypeScript to simplify reading context and applying consistent styling.

* [Python SDK](/plugins/python) — `pip install overseer-sdk`
* [TypeScript SDK](/plugins/typescript) — `npm install overseer-sdk`
* [Native plugins](/plugins/native) — Built-in plugin reference

---

---
url: /overseer/plugins/native.md
---
# Native plugins

Native plugins are compiled into the overseer binary. They differ from external plugins in that they:

* Require no external executables or published repos
* Can hook deeply into `daily` and `status` without process spawning
* Are enabled/disabled via config rather than by adding or removing executables

## Listing native plugins

```bash
overseer plugins
```

Shows all native plugins with their enabled/disabled state.

## Enabling and disabling

Each native plugin has a default enable condition (typically: enabled when its integration section is non-empty). Override this explicitly with `plugins.settings`:

```yaml
plugins:
  settings:
    jira:
      enabled: false   # disable even if integrations.jira[] is populated
    claude:
      enabled: true    # opt-in plugins require explicit enable
```

## Built-in plugins

### `jira`

Jira issue tracking integration.

* **Default**: enabled when `integrations.jira[]` is non-empty
* **daily**: shows open issues assigned to you, per instance
* **status**: auth ping per configured instance

### `slack`

Slack workspace integration.

* **Default**: enabled when `integrations.slack[]` is non-empty
* **daily**: shows recent mentions, per workspace
* **status**: auth ping per configured workspace

### `google`

Google Calendar integration.

* **Default**: enabled when `integrations.google[]` is non-empty
* **daily**: shows today's events, per account
* **status**: OAuth token validity per account

### `github`

GitHub pull request integration.

* **Default**: enabled when `integrations.github[]` is non-empty
* **Commands**: none (PRs are shown via `overseer prs`)
* **daily**: none
* **status**: none (visible in `overseer plugins` for awareness)

### `gitlab`

GitLab merge request integration.

* **Default**: enabled when `integrations.gitlab[]` is non-empty
* **Commands**: none (MRs are shown via `overseer prs`)
* **daily**: none
* **status**: none

### `obsidian`

Obsidian vault integration.

* **Default**: enabled when `obsidian.vault_path` is set
* **status**: checks that the vault path exists on disk

### `claude`

Claude AI configuration management. Manages symlinks between the brain and `~/.claude/`.

* **Default**: disabled — must be explicitly enabled
* **Commands**: `overseer claude setup`, `overseer claude list`
* **status**: symlink health for all managed Claude config targets

**Enable:**

```yaml
plugins:
  settings:
    claude:
      enabled: true
```

**Brain layout** (`<brain>/claude/`):

| Brain path | Local target | Link type |
|---|---|---|
| `claude/CLAUDE.md` | `~/.claude/CLAUDE.md` | file symlink |
| `claude/settings.json` | `~/.claude/settings.json` | file symlink |
| `claude/plans/` | `~/.claude/plans` | whole-dir symlink |
| `claude/memory/` | `~/.claude/memory` | whole-dir symlink |
| `claude/hooks/<name>` | `~/.claude/hooks/<name>` | per-file symlinks |
| `claude/skills/<name>/` | `~/.claude/skills/<name>` | per-dir symlinks |

Run `overseer claude setup` to adopt existing files, migrate old symlinks, and create any missing links. The wizard is safe to re-run — already correct symlinks are skipped.

## Writing a native plugin

Add a new package under `cli/internal/plugins/<name>/`:

```go
package myplugin

import (
    "github.com/arthurvasconcelos/overseer/internal/config"
    "github.com/arthurvasconcelos/overseer/internal/nativeplugin"
)

func init() {
    nativeplugin.Register(&nativeplugin.Plugin{
        Name:        "myplugin",
        Description: "What my plugin does",
        IsEnabled:   func(cfg *config.Config) bool { ... },
        DailyItems:  func(cfg *config.Config) []nativeplugin.DailyTask { ... },   // optional
        StatusChecks: func(cfg *config.Config) []nativeplugin.StatusCheckFn { ... }, // optional
        Commands:    func(cfg *config.Config) []*cobra.Command { ... },            // optional
    })
}
```

Then add a blank import to `cli/cmd/plugins_init.go`:

```go
_ "github.com/arthurvasconcelos/overseer/internal/plugins/myplugin"
```

That's it — the plugin is automatically wired into `daily`, `status`, and the help output.

---

---
url: /overseer/plugins/python.md
---
# Python SDK

The Python SDK provides helpers for reading the overseer context and applying consistent terminal styling.

[![PyPI](https://img.shields.io/pypi/v/overseer-sdk)](https://pypi.org/project/overseer-sdk/)

Source: [`sdk/python/`](https://github.com/arthurvasconcelos/overseer/tree/main/sdk/python)

## Install

```bash
pip install overseer-sdk
```

## Reading context

```python
from overseer_sdk import PluginContext

ctx = PluginContext.from_env()

print(ctx.version)      # overseer version string
print(ctx.config_path)  # path to merged config file

# Retrieve a resolved secret declared in the sidecar manifest
token = ctx.secret("github.personal", "token")
```

`PluginContext.from_env()` reads and parses the `OVERSEER_CONTEXT` environment variable injected by overseer at runtime.

## Styling

```python
from overseer_sdk import section_header, warn_line, ok_line, error_line

# Section header
print(section_header("Deployments", "production"))
# → ▸ Deployments  ·  production

# Warning line
print(warn_line("auth", "token expired"))
# → ⚠  auth: token expired
```

### Color tokens

| Token | Code | Color | Usage |
|---|---|---|---|
| `STYLE_HEADER` | 99 | Purple | Section titles (bold) |
| `STYLE_ACCENT` | 212 | Pink | Keys, channels, usernames |
| `STYLE_OK` | 82 | Green | Success states (bold) |
| `STYLE_WARN` | 214 | Amber | Warnings (bold) |
| `STYLE_ERROR` | 196 | Red | Errors (bold) |
| `STYLE_MUTED` | 240 | Dark grey | Hints, empty state |
| `STYLE_DIM` | 245 | Grey | Secondary info |
| `STYLE_NORMAL` | 252 | Light | Body text |

All color codes use the xterm 256-color palette, which works in any modern terminal.

## Hooks

Use `run_main` to wire up your plugin's `daily` and `status` hooks:

```python
from overseer_sdk import PluginContext, StatusResult, run_main

def daily(ctx: PluginContext) -> str:
    token = ctx.secret("myservice", "token")
    return "▸ My Service\n  all good\n"

def status(ctx: PluginContext) -> list[StatusResult]:
    return [StatusResult(name="myservice", ok=True, message="connected")]

if __name__ == "__main__":
    run_main(daily_fn=daily, status_fn=status)
```

## Example plugin

Make the file executable and name it `overseer-myplugin`, then drop it in `brain/overseer/plugins/`.

```python
#!/usr/bin/env python3
from overseer_sdk import PluginContext, section_header

ctx = PluginContext.from_env()
print(section_header("My Plugin", ctx.version))
# ... your plugin logic
```

---

---
url: /overseer/plugins/typescript.md
---
# TypeScript SDK

The TypeScript SDK provides helpers for reading the overseer context and applying consistent terminal styling.

[![npm](https://img.shields.io/npm/v/overseer-sdk)](https://www.npmjs.com/package/overseer-sdk)

Source: [`sdk/typescript/`](https://github.com/arthurvasconcelos/overseer/tree/main/sdk/typescript)

## Install

```bash
npm install overseer-sdk
```

## Reading context

```typescript
import { loadContext, getSecret } from "overseer-sdk";

const ctx = loadContext();

console.log(ctx.version);      // overseer version string
console.log(ctx.config_path);  // path to merged config file

// Retrieve a resolved secret declared in the sidecar manifest
const token = getSecret(ctx, "github.personal", "token");
```

`loadContext()` reads and parses the `OVERSEER_CONTEXT` environment variable injected by overseer at runtime.

## Styling

```typescript
import { sectionHeader, warnLine, okLine, errorLine } from "overseer-sdk";

// Section header
console.log(sectionHeader("Deployments", "production"));
// → ▸ Deployments  ·  production

// Warning line
console.log(warnLine("auth", "token expired"));
// → ⚠  auth: token expired
```

### Color tokens

| Token | Code | Color | Usage |
|---|---|---|---|
| `styles.header` | 99 | Purple | Section titles (bold) |
| `styles.accent` | 212 | Pink | Keys, channels, usernames |
| `styles.ok` | 82 | Green | Success states (bold) |
| `styles.warn` | 214 | Amber | Warnings (bold) |
| `styles.error` | 196 | Red | Errors (bold) |
| `styles.muted` | 240 | Dark grey | Hints, empty state |
| `styles.dim` | 245 | Grey | Secondary info |
| `styles.normal` | 252 | Light | Body text |

All color codes use the xterm 256-color palette, which works in any modern terminal.

## Hooks

Use `runMain` to wire up your plugin's `daily` and `status` hooks:

```typescript
import { runMain, getSecret } from "overseer-sdk";
import type { PluginContext, StatusResult } from "overseer-sdk";

async function daily(ctx: PluginContext): Promise<string> {
  const token = getSecret(ctx, "myservice", "token");
  return "▸ My Service\n  all good\n";
}

async function status(ctx: PluginContext): Promise<StatusResult[]> {
  return [{ name: "myservice", ok: true, message: "connected" }];
}

runMain({ daily, status });
```

## Example plugin

Compile your script to a single executable (e.g. with `esbuild`), name it `overseer-myplugin`, and drop it in `brain/overseer/plugins/`.

```typescript
import { loadContext, sectionHeader } from "overseer-sdk";

const ctx = loadContext();
console.log(sectionHeader("My Plugin", ctx.version));
// ... your plugin logic
```

---

---
url: /overseer/llms.md
---

# For LLMs

overseer provides machine-readable documentation endpoints so AI assistants and LLM-powered tools can understand this CLI accurately.

## llms.txt

A concise index of the documentation — titles, descriptions, and links. Follows the [llms.txt standard](https://llmstxt.org/){target="\_blank"}.

llms.txt

## llms-full.txt

The full content of every documentation page in a single plain-text file. Best for feeding directly into a context window.

llms-full.txt

## Per-page Markdown

Append `.md` to any documentation URL to get that page as raw Markdown.

/commands/daily.md

---

---
url: /overseer/install.md
description: >-
  Install overseer via Homebrew or from source, run the setup wizard, and
  configure shell completions.
---

# Installation

## Homebrew (macOS)

**Stable channel** (recommended):

```bash
brew install arthurvasconcelos/tap/overseer
```

**Beta channel** (pre-release builds):

```bash
brew install arthurvasconcelos/tap/overseer-beta
```

## Manual install

Downloads and installs the latest binary to `~/bin/`:

**Stable channel** (recommended):

```bash
curl -fsSL https://raw.githubusercontent.com/arthurvasconcelos/overseer/main/scripts/install.sh | bash
```

**Beta channel** (pre-release builds):

```bash
curl -fsSL https://raw.githubusercontent.com/arthurvasconcelos/overseer/main/scripts/install.sh | bash -s -- --channel beta
```

Make sure `~/bin` is on your `PATH`:

```bash
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
```

## Build from source

Requires Go 1.21+.

```bash
git clone https://github.com/arthurvasconcelos/overseer.git
cd overseer
make dev
```

Builds and installs to `~/bin/overseer`.

***

## First-time setup

Run the interactive wizard after installing:

```bash
overseer setup
```

This walks through brain path, git remote, machine settings, directory scaffolding, dotfile wiring, and Brew packages in one session. Existing values are shown as defaults and nothing is overwritten without your input. Safe to re-run at any time.

If you already have a brain and only want to re-apply config without the full wizard:

```bash
overseer brain setup
```

***

## Shell completions

```bash
# Zsh
echo 'source <(overseer completion zsh)' >> ~/.zshrc

# Bash
echo 'source <(overseer completion bash)' >> ~/.bashrc

# Fish
overseer completion fish > ~/.config/fish/completions/overseer.fish
```