agd

agd is an org-agenda for the terminal and for coding agents. It reads the Org files and the Emacs or Neovim config you already have, shows them in a keyboard-first TUI, and lets Claude Code, Codex and other MCP clients read and write the same tasks. What is due this week, or a task for Thursday, is a glance or one line away from the pane you are working in, without opening an editor.

Your files stay yours: agd changes only the bytes it was asked to change, checks its agenda and its writes against a pinned Emacs, and keeps every agent write in a tab until you accept or undo it.

New to Org? Org keeps notes and tasks in plain text files (* TODO Renew passport), and org-agenda is its view of what is scheduled, due and open across them. agd is that view outside Emacs, and it starts on an empty ~/org with Org's defaults.

Try it on sample data without touching your files (needs python3):

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

On Arch, cd packaging/aur && makepkg -si in a clone builds the release. Tagged releases publish binaries for Linux, macOS and Windows with a Sigstore-signed SHA256SUMS. Completions come from agd completions bash|zsh|fish|elvish|powershell.

Start

Bring your Emacs or Neovim setup once, then run agd:

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

The import runs a clean emacs -Q or nvim --clean that reads your config files without running your startup, and writes ~/.config/agd/config.toml with your org directory, agenda files, TODO keywords, logging, priorities, capture templates and custom agenda commands. It names the file and line each setting came from, and why it left anything out. Starting fresh needs no config: mkdir ~/org, then agd. Getting started walks through both, and a first day with agents.

The TUI

• Today opens first, or the saved view named by start_view: OVERDUE, SCHEDULE, DUE SOON, DOING and INBOX, in the order you act on them. v swaps in org-agenda's classic day list.
• Week, Inbox and Agents are tabs, and a opens your saved views like C-c a.
• Triage (T) walks the overdue items, then the inbox, one card and one key per decision. u undoes a step, or the whole pass.
• Capture (c) takes one line and previews the exact Org text it will write.
• Agents lists every agent write, who made it and from which project, until you accept or undo it.
• agd --pane is a narrow glance for a split: overdue as a count, the day's times with ▸ on the next, and the inbox and Agents counts.

Keys follow org-agenda wherever it has one:

Every key, screen by screen, is in KEYS.md. Color only carries meaning: lateness, deadlines, done, focus and agents. theme = "auto" follows the terminal's background, and NO_COLOR is respected.

Capture

The same line works in agd capture, the TUI's c and Claude Code's /capture:

agd capture "Renew passport due:fri #personal !A"
agd capture t "Dentist on:fri 14:00"
agd capture "Pay rent due:2026-11-01 +1m -3d #home"

The first word picks a template when it is one of your [[capture]] keys. due: sets a deadline and on: schedules, with any date Org's date prompt reads (fri, +2d, oct 30, fri 9am), then a repeater and a warning. #tag and !A add a tag and a priority, or :tag: and #A with notation = "org"; #42 stays text. Text that starts with - goes after --. In the TUI, M-⏎ adds a checklist line under the task, x checks one off in the edit popup, and lists show the progress, 1/3.

With agents

In Claude Code, install agd as a plugin:

claude plugin marketplace add johnnybravo-xyz/agd
claude plugin install agd@johnnybravo-xyz

It brings the MCP server, the agenda skill and a mod (Claude Code 2.1.296 or later): /agd opens a pane beside the transcript with your start view and saved views, /capture t text files a task without a Claude turn, and a line above the prompt shows the day's counts. For Codex and OpenCode, install the MCP server and skill in a project (--dry-run shows the diff):

agd setup install --directory . codex      # or opencode

agd mcp is a stdio MCP server with seven tools: agenda, query, describe, capture, edit, plan and set_state. It never opens a network port, and your agenda reaches a model only when it calls one of them.

• Every agent write is journaled under the agent's name and project, and waits on the Agents tab until you accept or undo it.
• Agents add REPO, BRANCH and a SOURCE link to what they capture, so a task says where it came from.
• agent_inbox = "t" sends agent captures through template t without dates: agents can add work, but not plan your day.

Panes and status bars

tmux split-window -h -l 36 'agd --pane'                 # a glance beside your agent

# ~/.tmux.conf
bind T display-popup -E -w 80 -h 22 'agd capture -i'    # prefix T: capture from anywhere
set -g status-right '#(agd agenda --status)'            # 1 overdue · 3 today · 9 inbox · 2 unreviewed

herdr panes take agd --pane the same way. The pane and the TUI watch your files, so changes from Emacs, Neovim or an agent show up as they happen.

Command line

agd                    the TUI
agd --pane             the narrow pane
agd agenda             the agenda as org-agenda prints it, or --json, --csv, --status
agd capture            one line through a template, or the popup with -i
agd undo               undo your latest command-line change
agd mcp                the stdio MCP server for coding agents
agd setup import       your Emacs or Neovim org settings into config.toml
agd setup install      the MCP server and skill for Codex or OpenCode
agd setup check        parse drift, invalid UTF-8, duplicate IDs, interrupted writes
agd completions SHELL  shell completions

agd agenda --view n                                  # a saved view, like C-c a n
agd agenda --match 'work-someday/NEXT|TODO' --json
agd capture "Renew passport due:fri" --dry-run

Piped, agd agenda prints exactly Org's text. JSON items carry a stable ref, and errors with --json are agd.error/v1 objects with a code such as ref_conflict or invalid_date.

Configuration

One flat file, ~/.config/agd/config.toml (or $XDG_CONFIG_HOME/agd) on Linux and macOS alike. Missing keys take their defaults and unknown keys are errors. Values reuse Org's names:

roots = ["~/org"]                 # the only directories agd reads or writes
agenda_files = ["**/*.org"]       # files, directories or globs under the roots

todo_keywords = ["TODO(t) NEXT(n) WAIT(w@/!) | DONE(d!) CANCELLED(c@)"]  # #+TODO: lines
todo_keyword_colors = { WAIT = "yellow", CANCELLED = "dim-red" }
agenda_span = "week"              # day, week, month or a number of days
log_done = "time"                 # off, time or note; also log_repeat, log_reschedule
log_into_drawer = true

editor = ["emacsclient", "-n", "+{line}:{col}", "{file}"]
notation = "agd"                  # #tag and !A; "org" for :tag: and #A
start_view = "w"                  # open on this view instead of Today
agent_inbox = "t"                 # agents capture through this template, without dates

[[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" },
  { kind = "alltodo", header = "Backlog", groups = [   # org-super-agenda groups
    { name = "Overdue", match = 'DEADLINE<"<today>"' },
    { name = "Quick", effort_max = "0:15" },
    { by = "category" },
  ] },
]

Compatibility and safety

Agenda rows and their order, the text and CSV agendas, and every write are compared byte for byte with a pinned Emacs 30.2 and Org 9.7. Repeaters and habits, sorting strategies, tag inheritance, custom agenda command blocks and logging match; regexp matches, diary sexps, skip functions and clocking are reported and never evaluated.

• agd reads and writes only under roots, and never writes through a symlink.
• A write locks, re-reads the file, refuses a stale or ambiguous target or a file Emacs holds unsaved changes for, patches only its bytes, journals the inverse and renames atomically.
• Undo applies only where those bytes are unchanged; anything else is a conflict, never an overwrite.
• No network access at runtime.

More

• Getting started, KEYS.md, IMPORTING.md, COMPATIBILITY.md, SAFETY.md
• DESIGN.md: the words, formats, keys and look every surface follows
• ARCHITECTURE.md, CONTRIBUTING.md, SECURITY.md

just check runs fmt, clippy, the tests, the plugin checks and nix flake check; just oracles compares agd with the pinned Emacs and Neovim in Docker.

agd started as 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.