---
name: obsidian
description: Manage Harry's Obsidian vault notes and Popdog task tracking with the Obsidian CLI. Use when registering tasks, reading or updating Popdog notes, rolling completed work into daily roundup notes, or searching the vault.
---

# Obsidian

Use the registered `obsidian` CLI for vault operations. The important working area is `Work/Popdog`, with `Work/Popdog/_Todo.md` as the outstanding-work index.

Obsidian CLI requires the desktop app to be running; if it is not running, the first command may launch it. Target this vault explicitly if needed with `vault=<name>` as the first parameter.

## Popdog Task Rules

Use this format in `Work/Popdog/_Todo.md`:

```markdown
- [ ] ==**High**== Task Title (Catwalk PR#)
  - [ ] Sub task/portion of task
- [ ] **Medium** Task Title (Harvester PR#)
  - [ ] Sub task/portion of task
- [ ] **Medium** Task Title (Harvester PR#, Catwalk PR#)
  - [ ] Sub task/portion of task
```

Only High priority receives `== ==` highlighting.

When a task is verified complete:

- Mark it complete in `_Todo.md`.
- Roll it into the daily roundup note named `YYYY-MM-DD.md`.
  - Daily roundups are delivered to the whole company, a mix of both devs and non-devs. The roundup should be accessible to both.
  - Personal notes can be added at the bottom of the document under a --- divider, this won't be sent as part of the roundup.
  - Daily roundups are bulleted, not checkboxes.
- Include the PR and repo next to completed work when known.

```markdown
- Task Title (Catwalk PR#)
- Task Title (Harvester PR#)
- Task Title (Catwalk PR#, Harvester PR#)
```

## Popdog Daily Roundup Style

Daily roundups should sound like Harry's practical engineering update, not a polished changelog.

- Start new daily notes with `# Monday`, `# Tuesday`, etc.
- Use short bullets, usually 2-5 public bullets for the day.
- Group by repo only when useful: `**Catwalk**`, `**Harvester**`, `**Both**`.
- Prefer plain English over release-note phrasing.
- Explain the actual user/business impact, not just the implementation.
- Include technical detail when it explains why something mattered.
- Be direct about uncertainty: `seems`, `as far as I can tell`, `likely`, `should`, `WIP`, `not deployed`.
- Mention what is complete, what is in review, and what is still being investigated.
- Keep a casual tone where natural: `dodgy`, `hammering the database`, `slow as shit`, `cos it was bugging me` match the existing notes.
- Avoid sounding too neat, corporate, or exhaustive.
- Do not over-summarise into abstract outcomes like `improved reliability` unless followed by the concrete thing that changed.
- Use contractions naturally: `we're`, `I've`, `it'll`, `don't`.
- Use lowercase repo/product names when that is how Harry usually writes them: `harvester`, `catwalk`, `youtube`, `twitch`, unless at the start of a formal heading.
- Keep PR numbers when known, but do not make the note revolve around PR metadata.
- Include screenshots inline after the relevant bullet when useful.
- Put personal/internal scratch notes below `---` so they are not part of the company-facing roundup.

Preferred pattern:

```markdown
- [Thing] now [does the useful behaviour]. [Short reason/context if needed].
```

Good examples:

```markdown
- Catwalk now fetches twitch vod and clip data from Harvester
- Game names are now collated when filtering, you can search Pokemon and it'll pick up accented characters no problem
- Harvester Sync Jobs now time out after 10 minutes. When catwalk was deployed a job would get stuck in the "running" state and wouldn't get timed out for 60 minutes.
```

Avoid abstract agent-changelog phrasing:

```markdown
- Improved Harvester operational resilience by implementing a stricter execution timeout policy for synchronization workloads.
- Enhanced game discovery by normalizing multilingual filter behaviour.
- Continued progress on Discover page performance optimizations.
```

## Agent Workflow

1. Read the relevant note before changing it: `obsidian read path="Work/Popdog/_Todo.md"`.
2. Use `obsidian tasks path="Work/Popdog/_Todo.md" verbose` when you need line numbers for task updates.
3. Prefer CLI mutations (`task`, `append`, `prepend`, `create`) over manual file editing when they fit.
4. Use exact `path=` values for Popdog files; use `file=` only when the name is unambiguous.
5. After updates, re-read the touched note to verify the result.

## Common Commands

```bash
obsidian read path="Work/Popdog/_Todo.md"
obsidian tasks path="Work/Popdog/_Todo.md" todo verbose
obsidian task path="Work/Popdog/_Todo.md" line=12 done
obsidian append path="Work/Popdog/2026-05-11.md" content="- [x] Task Title (PR# - Repo)"
obsidian create path="Work/Popdog/2026-05-11.md" content="# 2026-05-11" open
obsidian search query="billing" path="Work/Popdog"
```

## CLI Notes

- Parameters use `key=value`; quote values with spaces.
- Flags are bare words, for example `open`, `overwrite`, `todo`, `done`, `verbose`.
- Multiline content uses `\n` and tabs use `\t`.
- Add `--copy` to copy command output to the clipboard when useful.

See [the CLI reference](references/cli-reference.md) for agent-oriented command coverage from the official Obsidian CLI docs.