obia

README

Obia

Your Obsidian vault, in the terminal. A fast, interactive TUI for managing tasks across your entire vault — no Obsidian needed.

Obia scans every .md file in your Obsidian vault, pulls out - [ ] tasks, and lets you browse, filter, toggle, add, edit, and sync them from your terminal. Built with Bubble Tea.

---

Features

• All your tasks, one place — Parses - [ ] / - [x] from every markdown file in your vault
• Tabbed views — Fully configurable tabs (defaults: Tasks, Overdue, CalDAV) — switch with Tab
• Vim-style navigation — j/k to move, g/G for top/bottom
• Toggle done — Hit Enter to check/uncheck, writes back to the .md file instantly
• Open in editor — Press Ctrl+G to open the task's source file in $EDITOR at the exact line
• Instant startup — Task list appears immediately from cache; background scan refreshes silently
• Rich task add — Press a to open a form: summary, target file (fuzzy picker), due date, time, description, priority, status, optional CalDAV push
• Edit tasks — Press e to edit any task; plain tasks auto-upgrade to linked tasks when metadata is set
• Fuzzy search — / to filter with fuzzy matching across all task descriptions
• Grouped view — Press v to toggle between flat list and tasks grouped by source file
• Task files — Linked tasks stored as tasks/<uid>.md with YAML frontmatter; wikilinks keep your vault clean
• CalDAV sync — Push tasks to any CalDAV server with p (Radicale, Nextcloud, iCloud, Tasks.org, etc.)
• CalDAV pull — Press R to pull all VTODOs from your CalDAV server; new remote tasks land in your inbox
• CalDAV auto-push — Optionally push new tasks to CalDAV automatically on add
• Green CalDAV indicator — Synced tasks render in green so they're visually distinct
• Wikilinks & tags — Extracts [[links]] and #tags from task descriptions
• Fast — Scans 800+ files in under a second

---

Install

go install github.com/hawkaii/obia@latest

Or build from source:

git clone https://github.com/hawkaii/obia.git
cd obia
go build -o obia .

---

Getting Started

1. Create a config

Obia looks for its config at ~/.config/obia/config.toml. Create one:

mkdir -p ~/.config/obia

[vault]
path = "/path/to/your/obsidian/vault"
daily_notes_folder = "diary"
daily_notes_format = "2006-01-02"
default_task_file = "todo.md"
add_task_target = "daily"       # default target when pressing `a`: "daily" or "default"
task_files_folder = "tasks"     # folder where task files (tasks/<uid>.md) are stored
inbox_file = "tasks/inbox.md"   # file where pulled CalDAV tasks are appended
extra_targets = [               # additional target files shown in the add/edit form picker
    "projects/work.md",
    "projects/personal.md",
]

[caldav]
url = ""
username = ""
password = ""
auto_push = false               # push new tasks to CalDAV automatically on add

# Tab configuration (optional — defaults to Tasks, Overdue, CalDAV if omitted)
[[ui.tabs]]
name = "Tasks"
filter = "open"

[[ui.tabs]]
name = "Overdue"
filter = "overdue"

[[ui.tabs]]
name = "CalDAV"
filter = "caldav"

[[ui.tabs]]
name = "Daily"
filter = "folder"
folders = ["diary"]

[[ui.tabs]]
name = "Weekly"
filter = "timewindow"
window = "week"
folders = ["diary"]
# week_start = "monday"   # optional; default is "sunday"

2. Run it

obia

That's it. You'll see all your open tasks across the vault.

---

iOS Sync via iCloud (Reminders)

If you want tasks pushed from Obia to appear in the Reminders app on your iPhone, point Obia at iCloud's CalDAV server — no third-party server needed.

1. Generate an app-specific password

1. Go to appleid.apple.com and sign in
2. Under Sign-In and Security, choose App-Specific Passwords → Generate
3. Name it something like obia and copy the generated password (xxxx-xxxx-xxxx-xxxx)

2. Add CalDAV config

[caldav]
url      = "https://caldav.icloud.com"
username = "your@icloud.com"
password = "xxxx-xxxx-xxxx-xxxx"   # app-specific password, NOT your Apple ID password

3. Sync

Action	How
Push a task to Reminders	Press p on any task, fill the form, submit
Push on add	Set auto_push = true in config, or toggle Push? in the add form
Pull tasks from Reminders	Press R — new remote tasks land in your inbox file
Toggle done syncs too	Checking/unchecking a linked task updates Reminders automatically

Tasks appear in the default Reminders list on iOS. They will not appear in the Calendar app — Reminders is Apple's CalDAV task store.

---

Keybindings

Key	Action
j / ↓	Move down
k / ↑	Move up
g / G	Jump to top / bottom
Tab / Shift+Tab	Switch tabs
Enter	Toggle task done/undone
Ctrl+G	Open task's source file in $EDITOR at the exact line
a	Add new task (opens rich form)
e	Edit task (summary, start date/time, due date/time, repeat, description, priority, status)
p	Upgrade plain task to linked task (opens form pre-filled)
R	Pull all tasks from CalDAV server
/	Fuzzy search / filter
v	Toggle flat / grouped-by-file view
r	Reload vault
Esc	Clear filter / cancel form
q	Quit

---

Tabs

Tabs are fully configurable in your config.toml under [[ui.tabs]]. When no tabs are configured, three defaults are injected: Tasks, Overdue, CalDAV.

Filter types

Filter	Description
open	All open tasks
overdue	Tasks past their due date
caldav	Tasks synced with CalDAV server
folder	Tasks from specific folders (folders required)
timewindow	Calendar-aligned window: week or month
rolling	N days forward from today (days required)
file	Tasks from a specific file (file required)
tag	Tasks with a specific tag (tag required)
wikilink	Tasks linking to a specific page (wikilink required)

Config example

[[ui.tabs]]
name = "Tasks"
filter = "open"

[[ui.tabs]]
name = "Overdue"
filter = "overdue"

[[ui.tabs]]
name = "CalDAV"
filter = "caldav"
show_done = true    # include completed CalDAV tasks

[[ui.tabs]]
name = "Diary"
filter = "folder"
folders = ["diary"]

[[ui.tabs]]
name = "Weekly"
filter = "timewindow"
window = "week"
folders = ["diary"]

[[ui.tabs]]
name = "This Month"
filter = "timewindow"
window = "month"
folders = ["diary"]

[[ui.tabs]]
name = "Next 14 Days"
filter = "rolling"
days = 14
folders = ["diary"]

[[ui.tabs]]
name = "DSA"
filter = "file"
file = "dsa.md"

[[ui.tabs]]
name = "Urgent"
filter = "tag"
tag = "urgent"

Time window options

For filter = "timewindow":

• window = "week" — current calendar week (aligned to week_start): sunday (default) or monday
• window = "month" — current calendar month

Rolling options

For filter = "rolling":

• days = 14 — N days forward from today

Both timewindow and rolling match against task due dates AND folder filenames (e.g., diary/2026-04-25.md). If folders is not set, filename-date matching is disabled and a warning appears in the tab.

Show done tasks

By default, done tasks are hidden. Set show_done = true on any tab to include completed tasks.

---

Task Model

Obia has two kinds of tasks:

Plain tasks

Standard Obsidian checkbox syntax in any .md file:

- [ ] buy groceries
- [x] finished task
- [ ] task with [[wikilink]] and #tag

Linked tasks

When you add metadata (due date, priority, etc.) or push to CalDAV, Obia creates a task file and rewrites the checkbox as a wikilink alias:

- [ ] [[3f8a1b2c-...|buy groceries]]

The task file at tasks/<uid>.md stores all the metadata:

---
type: task
caldav-uid: 3f8a1b2c-...
dtstart: 2026-04-01T09:00:00Z
due: 2026-04-02T09:00:00Z
rrule: FREQ=WEEKLY
priority: 5
status: NEEDS-ACTION
---

# buy groceries

Optional longer description here.

This keeps your vault markdown clean while preserving full CalDAV metadata.

---

CalDAV Sync

Obia syncs with any CalDAV-compatible server (Radicale, Nextcloud, iCloud, Tasks.org, etc.).

Fill in the [caldav] section of your config:

[caldav]
url = "https://your-server.com/radicale/user/calendar/"
username = "you"
password = "secret"

Push

Press p on a plain task to open the form — set start date/time, due date/time, repeat, description, priority, and status, then push. The task line is rewritten to [[uid|title]] and a task file is created.

When adding a new task with a, toggle the Push? field in the form to push immediately.

Pull

Press R to fetch all VTODOs from the server:

• Existing task files are updated (due date, status, priority)
• New remote tasks get a task file created and a - [ ] [[uid|title]] line appended to your inbox file (tasks/inbox.md by default)

Toggle sync

Toggling a linked task (checking/unchecking) automatically updates the task file status and pushes the change to CalDAV.

Auto-push

Set auto_push = true in [caldav] to push every new task automatically on add.

---

How It Works

~/.config/obia/config.toml
         │
         ▼
   ┌──────────┐     ┌─────────────┐
   │  Config   │────▶│ Vault       │
   │  Loader   │     │ Scanner     │──▶ finds all .md files
   └──────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ Task Parser │──▶ extracts - [ ] lines
                    │             │──▶ resolves [[uid|alias]] wikilinks
                    │             │──▶ hydrates due/status/priority from task files
                    └─────────────┘
                           │
                           ▼
                    ┌─────────────┐     ┌──────────┐
                    │ Bubble Tea  │◀───▶│ CalDAV   │
                    │ TUI         │     │ Client   │
                    └─────────────┘     └──────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ Writer      │──▶ toggles checkboxes in .md files
                    │             │──▶ creates/updates tasks/<uid>.md
                    └─────────────┘

---

Built With

• Bubble Tea — TUI framework
• Bubbles — Text input components
• Lip Gloss — Terminal styling
• go-toml — Config parsing
• sahilm/fuzzy — Fuzzy search

---

Works With

Obia works with any folder of markdown files — not just Obsidian. It only needs standard checkbox syntax and .md files.

Tool	Compatibility
Obsidian	Full
Logseq	Full — same - [ ] syntax, wikilinks, YAML frontmatter
Foam	Full — VS Code extension, same conventions
Zettlr	Full — standard markdown + frontmatter
Dendron	Full — VS Code extension, hierarchical .md files
Any folder of .md files	Full — VS Code, Neovim, iA Writer, etc.
Joplin	Partial — only with filesystem sync enabled
Org-mode / Roam / Notion	✗ — different formats

Point vault.path in your config at any markdown directory and Obia will scan it.

---

Roadmap

• Daily tab — all tasks from diary/*.md across all dates
• Config-driven tabs with [[ui.tabs]] — fully customizable browser tabs
• Stats overview panel — right-side stats sidebar (OpenCode-style) with task counts, due breakdown, CalDAV sync status, top tags/files; press s to toggle; auto-hide on narrow terminals
• Task detail view — press d to render tasks/<uid>.md as a preview overlay
• Open in Obsidian — press o to launch obsidian://open?vault=...&file=...
• CLI flags (Cobra) — --vault, --config, --debug, --no-tui
• First-run setup wizard
• mtime-based task caching (skip unchanged files)
• Multi-line description textarea

---

Sponsoring

If you find Obia useful, consider supporting the project:

Discord

Have questions or want to chat? Join the community:

License

MIT

---

Obia — your vault, your terminal, your tasks.
_{Named after obsidian. Built for people who live in the terminal.}