Agenda (agd)

An org-agenda for the terminal and for coding agents. agd reads the Org files and settings you already use with Emacs or nvim-orgmode, shows them in a keyboard-first TUI, and lets agents read and write the same tasks over MCP, without changing a byte it was not asked to change.

• Your setup keeps working. #+TODO lines, keyword logging markers, #+STARTUP options, custom agenda commands, capture templates, sorting strategy and tag columns are honored, not reinterpreted. Agenda rows, their order and every write are checked against a pinned Emacs.
• Built for the five moments you use an agenda: a glance in a split pane, the morning plan in Today, an end-of-day Triage, a one-line Capture from anywhere, and Agent review of what coding agents changed.
• Safe with your data. Writes patch only the bytes they mean to, refuse stale or ambiguous targets, respect Emacs lock files, and can be undone.

Try it on sample data without touching your files:

git clone https://github.com/johnnybravo-xyz/agd.git && cd agd
cargo build --release && AGD=target/release/agd docs/demo/demo.sh

Install

cargo install agd --locked                 # Rust 1.89+
brew install johnnybravo-xyz/agd/agd
nix run github:johnnybravo-xyz/agd

Tagged releases publish checksummed binaries for Linux, macOS and Windows with a Sigstore bundle for SHA256SUMS. The Arch recipe is in packaging/aur.

First run

Point agd at your editor config once, then start:

agd setup import ~/.doom.d               # or ~/.config/emacs, ~/.emacs.d, ~/.config/nvim
agd setup check
agd

The import reads your config files (it never runs your editor's startup) and writes ~/.config/agd/config.toml with your org directory, agenda files, TODO keywords, logging, priorities, capture templates and custom agenda commands. It reports each setting with the file and line it came from, and anything it left out with the reason. From then on config.toml is yours to edit. New to Org? Skip the import: agd reads ~/org with Org's defaults. See docs/IMPORTING.md for exactly what imports and what does not.

The TUI

agd opens Today. Tabs switch to Week, Inbox and Agents (tab or 1–4); a opens your saved views like C-c a.

Keys follow org-agenda wherever it has one, so muscle memory carries over:

Colours carry state only (slipped, due, done, focus, one hue per agent). The theme follows the terminal's light or dark background ([tui] theme overrides it), falls back to 16 colours, and honours NO_COLOR.

tmux and herdr

tmux split-window -h -l 36 'agd --pane'                 # a glance beside your agent
tmux bind c display-popup -E -w 80 -h 22 'agd capture -i' # capture from anywhere
set -g status-right '#(agd agenda --status)'            # 3 slipped · 7 today · 2 agents
set -g set-clipboard on                                 # lets `y` reach your clipboard

The pane and the TUI watch your files, so changes from Emacs, nvim or an agent show up as they happen. herdr panes are mouse-native; click a row to select it, click it again to open the full TUI there.

Agents

agd mcp is a stdio MCP server with six tools (agenda, query, capture, set_state, plan, edit) and an agenda://today resource. It never opens a network port. Install it with the agd skill for your agent:

agd setup install --directory . claude      # or codex, opencode
agd setup install --directory . claude --with-session-agenda work

• Every agent write is journaled with the client's name and project, and shows up in Agent review until you accept or undo it.
• Agents pass properties such as REPO, BRANCH and SOURCE (an Org link back to the file and line) with a capture, so a task says where it came from.
• agents.capture_to = "inbox" sends every agent capture to your inbox without dates, so agents can add work but not plan your day.
• Session agenda is off by default; --with-session-agenda needs a named, filtered profile.

Command line

agd                 Today, Week, Inbox, Triage, Capture, Agent review
agd --pane          the narrow pane
agd agenda          the agenda as org-agenda prints it, or --json / --csv
agd capture         one line through a template, or the popup with -i
agd mcp             stdio MCP server for coding agents
agd setup import    your Emacs or Neovim org settings into config.toml
agd setup install   MCP server and skill for Claude Code, Codex, OpenCode
agd setup check     parse drift, invalid UTF-8 and duplicate IDs

agd agenda --span week                       # org-agenda layout
agd agenda --view n                          # a saved view, like C-c a n
agd agenda --match 'work-someday/NEXT|TODO' --json
agd agenda --csv                             # the columns of org-batch-agenda-csv
agd capture t "Renew passport due:fri +personal #A" --dry-run

JSON items carry a stable ref: the heading's :ID: when unique, otherwise file, line hint and content digest. Errors use stable codes such as stale_ref, duplicate_id, editor_dirty and symlink_write_refused.

Configuration

One flat file: ~/.config/agd/config.toml (or $XDG_CONFIG_HOME/agd) on Linux and macOS alike; --config picks another. Every setting is a top-level key; only capture templates, views and agent profiles are lists of records. Missing keys take the defaults shown; unknown keys are errors. The journal lives in ~/.local/share/agd (or $XDG_DATA_HOME/agd).

roots = ["~/org"]                 # the only directories agd reads or writes
agenda_files = ["**/*.org"]       # files, or globs relative to the roots; empty = all

todo_keywords = [["TODO(t)", "NEXT(n)", "WAIT(w@/!)", "|", "DONE(d!)", "CANCELLED(c@)"]]
ids = "preserve"                  # "add-on-write" adds an org-id :ID: on first edit
tags_column = -77                 # org-tags-column

agenda_span = "week"
deadline_warning_days = 14
sorting_strategy = ["habit-down", "time-up", "urgency-down", "category-keep"]
log_done = "time"                 # org-log-done; also log_repeat, log_reschedule,
log_into_drawer = true            # log_redeadline; #+STARTUP options win per file

editor = ["emacsclient", "-n", "+{line}:{col}", "{file}"]  # run directly, no shell
theme = "auto"                    # dark, light
agent_capture_to = "template"     # or "inbox"
someday_tag = "someday"
reschedule_nudge = 3

[[capture]]
key = "t"
desc = "Todo"
file = "inbox.org"
heading = "Inbox"
template = "* TODO %?\n:PROPERTIES:\n:CREATED: %U\n:END:"

[[view]]                          # an org-agenda custom command
key = "w"
desc = "Work"
blocks = [
  { kind = "agenda", span = "day" },
  { kind = "tags-todo", match = "work/NEXT|WAIT", header = "Next and waiting" },
]

Compatibility

Agenda rows and their order are compared with org-batch-agenda-csv from a pinned Emacs 30.2 with Org 9.7; writes are compared byte for byte with what the same Emacs writes. Full tables are in docs/COMPATIBILITY.md.

Safety

• Only files under files.roots are read or written; symlinks that leave the roots are refused, and writes never follow symlinks.
• A write re-reads the file under a lock, refuses Emacs's unsaved-buffer lock, patches only its bytes, preserves mode and line endings, journals the inverse patch with fsync, and renames atomically.
• Undo applies the inverse only where those bytes are unchanged; anything else is a conflict, never an overwrite.
• No network access at runtime. Editor import is an explicit local command.

Details: docs/SAFETY.md.

Development

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
nix flake check

agd/ is the executable (CLI, TUI, MCP), org-core/ the agd-core library (parsing, agenda, writes), and conformance/ the Emacs and nvim-orgmode oracle fixtures with their scripts in scripts/. vhs docs/release/agd.tape records the GIF above from docs/demo.

Origin and license

A fork of szaffarano/org-mcp-server. The combined work is GPL-3.0-or-later; upstream-derived code remains available under its MIT license in LICENSE-MIT.