ogent：在 Org-mode 中用 LLM 构建结构化智能体工作流

╭──────────────────────────────────────╮
│                  █                   │
│                 ███                  │
│                █████                 │
│               ╱  █  ╲                │
│              ╱   █   ╲               │
│             ┌┘   █   └┐              │
│             │  ╔═╩═╗  │              │
│             │  ║ ✦ ║  │              │
│             │  ╚═╦═╝  │              │
│             ┌┴───┴───┴┐              │
│            │ ◣█▏   ▕█◢ │             │
│            │  ▀▀   ▀▀  │             │
│            ├┐ ┌─────┐ ┌┤             │
│            │║ │▆▆▆▆▆│ ║│             │
│            │║ └─────┘ ║│             │
│             └╨───────╨┘              │
│                                      │
│    _____ _____  _____ _   _ _____    │
│   |  _  |  __ \|  ___| \ | |_   _|   │
│   | | | | |  \/| |__ |  \| | | |     │
│   | | | | | __ |  __|| . ` | | |     │
│   \ \_/ / |_\ \| |___| |\  | | |     │
│    \___/ \____/\____/\_| \_/ \_/     │
│                                      │
│         · agentic org-mode ·         │
╰──────────────────────────────────────╯

Use LLMs in structured Org workflows

ogent brings language models into Org-mode the Emacs way: composable commands with text + org-mode as the universal interface.

Exoskeleton + Agent

ogent is designed around this constraint:

• Make review fast: Responses land in Org blocks you can fold, diff, and navigate with standard keybindings. Tree based navigation beats scrolling and C-c C-c beats ad-hoc copy pasting for context management.
• Make context explicit: You declare what goes in via @handles, pins, and codemap. Obviously just giving it the whole project works too.

Features

• Context as data: @handles resolve to Org nodes, files, or org-roam entries. Codemap indexes your project. Pins persist across requests.
• Responses as structure: Output lands in src blocks with metadata (:model, :status, :latency). Fold them, edit them, version them. It’s just Org.
• Edits as diffs: Code changes render as smerge conflicts. Accept with C-c C-c, reject with C-c C-k.
• Commands: C-c . RET runs the current bullet as the prompt, with parent bullets passed as # Parent Bullets context. C-c . q asks a new minibuffer question about the current subtree. C-c . ? shows the ask menu. C-c . p opens full dispatch. C-c . E requests code edits.
• Armory: A local agent workspace built from plain Org files. Armory gives you persistent agents, jobs, conversations, approvals, schedules, task boards, data views, git state, and generated app artifacts without leaving Emacs.

Requirements

• Emacs 29.1 or newer
• Org 9.8.7 or newer
• gptel 0.9.9.5 or newer for transport and model selection
• transient 0.13.5 or newer for command menus
• Optional: org-roam for cross-file handle resolution
• An LLM provider:
  • **OpenAI Codex / ChatGPT**: Reuse Codex CLI OAuth credentials
  • **Claude Code / Claude Max/Pro**: Use OAuth authentication (recommended, no API key needed)
  • **API Key**: Traditional API key for Anthropic or OpenAI

Install

1. Clone the repository:

   git clone https://github.com/ryjm/ogent.git
   cd ogent
       

2. Ensure dependencies compile cleanly:

   make lint
   make test
       

3. Add lisp/ and lisp/ui/ to your load-path, then require ogent:

   (add-to-list 'load-path (expand-file-name "lisp" "/path/to/ogent"))
   (add-to-list 'load-path (expand-file-name "lisp/ui" "/path/to/ogent"))
   (require 'ogent)
       

Agent tools and local checks

Use familiar names, named arguments, and structured results after loading ogent. These local SDK workflows need no provider login or inference:

(ogent-agent-describe "read" 'json) ; Exact arguments, aliases, examples, and approval policy
(let ((page (ogent-agent-call "read" '(:file_path "README.org" :limit 20))))
  (ogent-agent-next page))         ; Follow the exact position; reject changed snapshots
(ogent-agent-batch
 '[(:tool "files" :args (:pattern "**/*.el" :limit 5))
   (:tool "search" :args (:pattern "defun" :path "lisp" :limit 5))])
(ogent-agent-capabilities 'json)   ; All live tool contracts
(ogent-agent-schema 'json)         ; Version 1 result envelope schema
(ogent-agent-triage 'json)         ; Local health and next actions

Results separate status, data, error, and page continuations. Empty files and no matches succeed. Async calls deliver one terminal result; read-only batches validate the whole plan before running. Writes and shell commands retain the existing approval, edit review, and ledger flow.

Discovery reads the current registry; (ogent-tools-install-defaults) explicitly adds built-in specs when needed. Existing integrations keep text output by default; ogent-tools-result-format can opt registered calls into json. make test format=json and make lint format=json report actual compiler/test results with diagnostics on stderr. See the agent interface guide for pagination, async calls, bounds, and migration.

Configuration

Quick Setup (Recommended)

Run M-x ogent-onboard to interactively configure your LLM provider. This wizard:

1. Lets you choose between OpenAI Codex OAuth, Claude Code OAuth, or API key authentication
2. Guides you through the login process
3. Configures gptel backends automatically
4. Run M-x ogent-doctor at any time to check Emacs/package versions, gptel/backend state, br availability, and local OAuth caches without making network calls.

OpenAI Codex / ChatGPT OAuth

If you already use the Codex CLI with ChatGPT login, ogent reads supported credentials (including OAuth tokens) cached in $CODEX_HOME/auth.json or ~/.codex/auth.json:

(require 'ogent)
(ogent-codex-login)         ; Opens Codex browser login
(ogent-codex-login-device)  ; Device-code fallback for headless sessions

After login, choose OpenAI Codex / ChatGPT (OAuth - Recommended) in M-x ogent-onboard.

To check status: M-x ogent-codex-status To logout: M-x ogent-codex-logout

Claude Code / Claude Max/Pro OAuth

If you have a Claude Pro, Max, Team, Enterprise, or Console account, you can authenticate via the Claude Code-compatible OAuth flow:

(require 'ogent)
(ogent-claude-code-login)  ; Opens browser, paste the code

This stores refresh tokens in ~/.emacs.d/ogent/anthropic-oauth/ and automatically refreshes them as needed, so there is no API key to manage.

Vanilla Emacs (API Key)

(add-hook 'org-mode-hook #'ogent-mode)
(setq ogent-default-model "gpt-6.1-sol")

Doom Emacs

(package! ogent :recipe (:local-repo "/path/to/ogent/lisp" :files ("*.el" "ui/*.el")))
(use-package! ogent
  :after org
  :init
  (setq ogent-enable-doom-bindings t
        ogent-doom-prefix "o")
  :config
  (ogent-setup-doom-bindings)
  (ogent-global-mode 1))

Usage

• Open any Org buffer and toggle ogent-mode (or rely on ogent-global-mode).
• Write a normal Org bullet/heading, then press C-c . RET to run that subtree as the prompt; ogent inserts a compact Request: / Response transcript below it.
• Parent bullets are sent explicitly under # Parent Bullets for Zen runs: each parent contributes its own body text, never its children, so nothing is duplicated and prior transcripts never leak into the payload.
• Workspace selection is prose-first: a bullet like look in ~/vault/projects/ogent for ideas makes that directory the request workspace. Explicit labels (Context:, Workspace:, Project:, Repo:) still work, but are optional. The payload shows a # Workspace section, relative ogent tool paths resolve from that root, and code-grounded wording asks gptel to use read-only tools before answering.
• Re-run a bullet from anywhere inside its transcript: C-c . RET appends a fresh run, C-c . ! (or C-c C-c on the transcript) replaces it. Earlier runs collapse automatically when a new run starts.
• Press C-c . q to ask a new minibuffer question about the subtree at point.
• Press C-c . ? when you are unsure: the ask menu names the active scope and offers run-current-bullet, re-run, inline ask, popup ask, malleable region ask/rewrite, edit application, context preview, and the full dispatcher.
• Press C-c . p to open the dispatcher, pick models, and send the current subtree.
• Doom/Evil users get the same command surface under SPC o when ogent-setup-doom-bindings or evil bindings are active.
• Use C-c . c for a context preview and C-c . m to inspect the codemap.
• Press C-c . d to capture the last AI response to a Notes child heading.
• To attach reusable prompt snippets, create Org nodes with an OGENT_ID (see docs/prompts.org).

Zen notebook presentation

ogent-zen-mode (enabled with ogent-mode in Org buffers; see ogent-zen-enable-in-org) keeps the page quiet without touching the stored text. To turn it on for every Org buffer independently of ogent-mode, enable global-ogent-zen-mode (it activates in Org buffers only and skips internal scratch buffers):

• Heading stars compose into a uniform bullet (ogent-zen-bullet, default •; skipped automatically when org-modern, org-bullets, or org-superstar is active).
• Generated Request: / Response headings render as compact run cards: expanded requests stay prompt-first, while folded completed requests become result-first indexes such as ✓ 10 grounded ideas · from “Better headline display”. Folded results can add a muted virtual preview line (ogent-zen-folded-result-preview) without changing the stored Org. Request metadata is split into outcome badges and lower-priority right-aligned metadata when the window can support it; density is customizable with ogent-zen-result-headline-density (minimal, balanced, rich, or debug). Multi-model runs show model chips, selected/accepted responses, and sibling lineage such as latest or superseded by newer run. Active tool work is promoted into the main title (reading lisp/ogent-zen.el · Headline idea) rather than buried in a suffix. Tool-call failures stay as inline diagnostics instead of failing the run card; only request-level model/network/abort failures turn the headline red. Empty runs show 0 chars instead of a vague warning. Response headings are quieter secondary rows and, when folded, carry response-local result previews plus review badges. Zen review now persists a structured decision model (OGENT_DECISION, OGENT_REVIEW_STATUS, OGENT_USEFULNESS, OGENT_LINEAGE, OGENT_OUTCOME, timestamps, reviewer, and a visible :REVIEW: drawer) while keeping legacy OGENT_REVIEW in sync for older transcripts. Review can explicitly target the run or one response, can accept a response as the selected model, and exposes a queue/dashboard workflow under C-c ,. Active requests animate only in visible buffers (ogent-zen-pretty-headings). Parent breadcrumb suffixes are opt-in via ogent-zen-show-breadcrumbs. Overlay-local RET / r / u / e action hints and bindings are opt-in via ogent-zen-heading-actions so Evil and other modal keymaps keep owning those keys by default. Use C-c . w (ogent-zen-copy-response) anywhere in a Zen transcript to copy only the response body, without request metadata or headings. Malleable editing uses the same tree-context machinery at smaller scope: C-c . C-r (ogent-zen-run-region) asks about the active region, C-c . C-e (ogent-zen-edit-dwim) rewrites the active region / paragraph / sentence with a SEARCH/REPLACE response, and C-c . C-a (ogent-zen-apply-last-edit) replays the latest structured edit into an inline diff preview. Accept or reject the preview with ogent-zen-accept-edit / ogent-zen-reject-edit (or inline-diff-mode’s C-c C-c / C-c C-k). Tool calls no longer inline into the notebook: Zen records them out of band so repeated prompt submissions stay responsive, keeps a compact count on the request headline, and opens the full list (arguments, results, status) in a separate buffer with C-c . h (ogent-zen-show-tool-calls). Set ogent-zen-tool-calls-inline to restore the legacy inline :TOOL: drawers. Transcript property drawers and prompt blocks fold away immediately (ogent-zen-fold-noise), and earlier runs collapse with status, model, result titles, and superseded lineage when a new run starts (ogent-zen-collapse-previous-runs).
• Set ogent-zen-center-column to an integer (e.g. 80) to center the notebook in wide windows.

Disabling the mode restores plain Org; the underlying transcript is always standard Request: / Response text, so history replay and older tooling keep working.

Keybindings

Review Prefix

Armory

Armory turns a directory of Org files into a local agent workspace. Open M-x ogent-armory-home or press C-c . j. The Armory surface includes agents, jobs, conversations, lead action approvals, data browsing, ranked palette search, git state, settings, backup, registry import, help, app artifacts, and a schedule calendar. In M-x ogent-armory-tasks, press c or C-c c to capture a manual Inbox task with a short TODO-style prompt path.

Home puts attention and current work first. Press c to open an instruction draft, RET to inspect an item, R to retry it, and ? for contextual actions. The crest is optional through ogent-armory-home-show-logo. Agents and tasks fit their primary columns to the window; D opens their full comparison view. In Agents, f filters all record fields, including fields hidden by the compact layout; an empty filter restores the list.

M-x ogent-models-browse opens a provider-grouped catalog with descriptions, streaming support, role assignments, and recorded completion evidence when available. Use n/p to move, / to find a model, RET to switch the session, d to set the default, and D for the full Org table. Refresh and resizing retain the selected model and the originating Org pin. Browsing and opening a draft do not send provider requests. Under Evil, headers show gr for refresh while preserving gg and ordinary motion keys.

The UI inherits your theme and font. Set ogent-ui-layout-line-spacing to nil to inherit your spacing too. See the native UI design report for actual captures, research, and verification; the reusable Emacs design skills live in .codex/skills.

The composer keeps attachments separate from editable instructions and shows the run after submission. Approval lists expose full proposals with RET; a/r records a decision and d dispatches approved actions. Invalid proposals cannot be approved. Tool reviews show effects and complete arguments, with v/b to scroll and C-g to deny the call. The error reader offers RET to return to the request and r to retry its original context.

The workflow audit records offline keyboard journeys, native screenshots, performance observations and the compatibility matrix. Reusable skills now also cover performance, accessibility and packaging.

Schedule events come from OGENT_CRON jobs, agent heartbeat cron fields, one-shot OGENT_RUN_AFTER tasks, and conversations with OGENT_SCHEDULED_KEY. Missed past slots can be run directly from the schedule buffer.

Prompt Templates

ogent includes a library of reusable prompt templates for common workflows. Templates are defined in docs/prompts.org and can be referenced using @handle syntax.

Using Prompt Templates

Apply a template from the prompt dispatcher’s Templates infix (T in M-x ogent-prompt-dispatch), or with M-x ogent-prompt-insert, which inserts the composed template text at point. With the optional yasnippet integration (see below), type a template’s handle and press TAB to expand it inline:

@code-review

Composing Multiple Templates

Select more than one template from the Templates infix or ogent-prompt-insert; ogent concatenates them, ordered by each template’s compose-order. The @handle+@handle shorthand is accepted by the compose API (ogent-prompt-compose-from-string):

(ogent-prompt-compose-from-string "@code-review+@security-audit")

Available Templates

See docs/prompts.org for the full list and detailed instructions.

Creating Custom Templates

Create Org headlines with an OGENT_ID property:

** My Custom Review
:PROPERTIES:
:OGENT_ID: my-review
:END:
Review this code with special attention to:
- Our team's coding standards
- Integration with the legacy API

Per-Project Customization

Set ogent-project-prompts-file in .dir-locals.el to load project-specific templates:

((nil . ((ogent-project-prompts-file . "prompts.org"))))

Override existing templates with ogent-prompt-overrides:

((nil . ((ogent-prompt-overrides
          . (("code-review" . (:content "Review with our team standards...")))))))

Yasnippet Integration

Enable yasnippet integration for quick template insertion:

(add-hook 'org-mode-hook #'ogent-prompts-yasnippet-mode)

Then type @code-review and press TAB to expand the template.

Updating

Pull the latest changes, then rerun make lint and make test to confirm your environment still passes before hacking.

Contributing

See CONTRIBUTING.md for setup, testing, and pull request guidelines.

License

ogent is licensed under GPL-3.0-or-later. See LICENSE for the full license text.