ortg

mcp
Security Audit
Pass
Health Pass
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 67 GitHub stars
Code Pass
  • Code scan — Scanned 7 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

ORTG — 单文件纲要引擎:为 Claude Code / Codex 维护一份与代码对齐的全仓库纲要,改多文件前先写计划并核对

README.md

ORTG v2

English | 简体中文

ORTG maintains a project outline for AI coding agents and keeps it in sync with code, reducing repeated source reading. Each file has a one-line summary stored in ortg.tsv at the repository root. The model reads and updates outlines through MCP; hooks reconcile state, provide reminders, and check change plans.

Supports Claude Code and Codex. Repositories without ortg.tsv stay inactive until you explicitly request initialization or run ortg scan.

Install with a prompt · Build · Manual installation · Initialize · Daily use · FAQ

Install with a prompt

On Windows, Linux, or macOS, send this to a local Codex or Claude Code session:

Install https://github.com/dignfei/ortg

Restart the agent after installation, and respond to any permission or hook trust prompts.

Build

Requires Go 1.27 and uses only the standard library. Older Go installations may download the toolchain automatically; install it in advance for offline use.

git clone https://github.com/dignfei/ortg.git
cd ortg
CGO_ENABLED=0 go build -ldflags "-s -w" -o build/ortg .
ln -sf "$PWD/build/ortg" /usr/local/bin/ortg

You can place the binary in another directory on PATH. For Windows Codex, use the installer below. To build only the native Windows binary in PowerShell:

$env:CGO_ENABLED = "0"
go build -ldflags "-s -w" -o build\ortg.exe .

Restart your terminal and agent after changing PATH. See AGENTS.md for development instructions. Run the full test suite with go test ./...; some tests require bash and python, so use Linux, macOS, or WSL.

Install as a plugin

Run the manual installation commands below from the ORTG repository root. When not using the Windows installer, first make sure ortg is on PATH in the environment that starts your agent.

Claude Code

claude plugin marketplace add "$PWD"
claude plugin install ortg@ortg

Codex

Windows installer

Open PowerShell from the Start menu and run the installer from the ORTG checkout:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install-windows.ps1

The installer uses Go on Windows for a Windows checkout, or Go in the corresponding WSL distribution for a WSL checkout. It installs to %USERPROFILE%\.ortg\bin outside the MSIX app data directory, sets your user PATH, and installs and verifies the Codex plugin. Run it only from a checkout you trust; the execution policy option applies to this PowerShell process only. To use an existing Windows executable of the same version, append -BinaryPath path\to\ortg.exe.

On Linux and macOS:

codex plugin marketplace add "$PWD"
codex plugin add ortg@ortg

When “Hooks need review” appears, review this plugin and choose “Trust all and continue” if you trust it. Changes to hook content require confirmation again.

To avoid truncating large outlines, merge these settings into ~/.codex/config.toml before all TOML tables. The context window is capped by the model's limit:

model_context_window = 1000000
tool_output_token_limit = 500000

The Codex plugin includes its MCP configuration, sets ORTG_AGENT=codex, and forwards a custom CODEX_HOME. If you trust your local ORTG server, you can set its default tool approval policy:

[plugins."ortg@ortg".mcp_servers.ortg]
default_tools_approval_mode = "approve"

Add only missing settings and preserve existing servers and explicit permission policies. You do not need to change global approval settings. Trusting hooks and approving MCP tools are separate settings. This approval configuration was verified with Codex 0.159.3; see local MCP approval for details and sources.

Manual Codex MCP setup

If you are not using the plugin's MCP server, merge this table into the same configuration file. Keep the context and output budgets above all tables:

[mcp_servers.ortg]
command = "ortg"
args = ["mcp"]
env = { ORTG_AGENT = "codex" }
env_vars = ["CODEX_HOME"]
default_tools_approval_mode = "approve"

ORTG_AGENT selects Codex output budgeting; env_vars forwards a custom CODEX_HOME. On Windows, the configuration file is %USERPROFILE%\.codex\config.toml.

Choose either the plugin server or manual registration. Do not also copy hooks into settings.json or register the same ORTG server with claude mcp add, as this duplicates hooks and tools.

Upgrade

To have the agent upgrade ORTG, replace “Install” with “Update” in the prompt above. For a manual upgrade on Windows Codex, rerun the installer from the updated checkout and fully restart Codex. On other setups, rebuild the binary from the updated source, update the plugin, and restart your session. The plugin cache is an installation snapshot and does not follow your working tree automatically.

For Claude Code, after committing the changes, run:

claude plugin marketplace update ortg
claude plugin update ortg@ortg

If it still loads old hooks or manifests, uninstall the plugin, clear its cache, and reinstall:

claude plugin uninstall ortg@ortg
rm -rf ~/.claude/plugins/cache/ortg
claude plugin install ortg@ortg

Restart Codex after updating too, and confirm trust again when hooks change. Claude Code uses the Git commit hash as the plugin version; the Codex version is maintained in .codex-plugin/plugin.json.

Initialize a repository

Open your agent in the target repository and specify the outline scope:

Goal Example request Mode
Work on the current task “Create an ORTG outline for this task, then fix…” task
Outline the entire project “Initialize ORTG for the entire repository” build

The model creates the table with ortg_overview init=true and explicitly sets the mode. task maintains task-related outlines and leaves other files unknown. build covers documentation, core code, and other files, with reviews between stages. See initialization and task maintenance.

Before generating the first outlines, the model presents a bilingual language question and choices. The selection is stored in the JSON language field of ortg.tsv. You can later ask, “Change the outline language to English.” New and updated descriptions use that language; existing outlines stay unchanged by default. CLI help, status reports, confirmations, and mode/language argument errors switch immediately. Fixed format markers, internal model instructions, and hooks retain their existing text.

You can also create the table and choose the mode and language from the command line:

ortg scan
ortg header --mode task --language en

If the repository root contains an old overview.txt, initialization backs it up and attempts to import it. See legacy migration. Existing outlines can be maintained directly without reinitialization.

Daily use

Give the model your task directly, or first ask, “Are the outlines aligned?” The model checks current state, reads the outline, and inspects source and tests as needed.

  1. Make single-file changes directly. For multiple files, write target outlines and review the plan with ortg_review first.
  2. After changing each file, submit its outline with ortg_update and check affected files.
  3. Run validation required by the task and repository, and report failures or unverified parts.

The model performs these steps through tools. For unaligned files, you can choose to update their outlines, confirm alignment after manual review, or leave them for later. Manual confirmation applies only to reviewed content. Resumed sessions retain their records; outlines are delivered again after context compaction or clearing.

Common tools:

Tool Purpose
ortg_overview Read outlines, by module when needed
ortg_status Check current state; outlined, observed and ignored directories show only directory names and counts, while other files show paths
ortg_target / ortg_review Write and review change plans
ortg_update Submit current outlines for one or more files
ortg_header Set the header, mode, language, and file scope
ortg_align Confirm fingerprints after manual review without changing outline text

A file summary has the form filename[tags]: Role:responsibility | Uses:dependencies | API:public contracts | Constraints:constraints. Include only the responsibilities, dependencies, public interfaces, and cross-file constraints that other tasks need. Explain file-local implementation decisions and branch conditions in comments near the relevant code, where maintainers will see them when editing the file.

Full arguments, batch operations, rule pagination, and final review protocols are documented in the rules reference.

ORTG reminds you about observed test failures and unfinished checks. Aligned outlines, a successful process exit, or a review declaration do not replace actual validation. See validation rules for evidence requirements and limits.

Configure file scope

In ortg.tsv, file outlines and plans come first. The remaining groups are directory outlines, bare entries that need outlines, observations with retained outlines or plans, and excluded rows awaiting cleanup.

Fingerprint-only observations live in the local ortg.tsv.crc32.bin file, a TSV table of paths, CRC32 values, and modification times. The first save by the new ortg scan moves those rows out of an existing table, preserving their baselines and backing up the main table. ORTG adds a local Git exclusion before writing the side table. Use ortg_status to check for changes.

Usually, ask the model to “observe testdata” or “ignore node_modules”; it updates the configuration with ortg_header. Files fall into three categories:

Category Configuration Behavior
Outlined Default or keep_files Maintain a per-file outline
Observed observe_dirs / observe_files Track fingerprints and report changes
Excluded ignore_dirs / ignore_files Omit from the outline

You can also merge keys into the JSON object below the header in ortg.tsv, preserving other settings, then run ortg scan. For example:

{
  "observe_dirs": ["testdata"],
  "ignore_dirs": ["node_modules", "vendor"],
  "keep_files": ["vendor/critical.go"]
}

Precedence is built-in exclusions → keep_files → observation → ignores. Within each list, the last matching rule wins; ! negates a rule. See file scope.

These priorities control scanning and maintenance. Bulk output never expands files inside a directory with an outline or one matched by observe_dirs or ignore_dirs, even when keep_files or a file exception retains those files. ortg_overview filters their names and per-file outlines, including forced and module queries; ortg_status groups all reported states, including changes, deletions and plans, by directory and count. No directory outline is required for configured observed or ignored directories. Directory-list negations can explicitly remove a directory from that output scope.

Third-party code can use one outline for an entire directory. For example, ask the model to “describe vendored, including its purpose and upgrade process, and assign it to the module that uses it.” Submitting a directory outline automatically adds the directory to observe_dirs. Internal files still have local fingerprints, but their names and outlines are no longer sent individually. Existing directory outlines behave the same way without manual configuration. Directory outlines take precedence over internal files, and keep_files cannot restore individual delivery. ortg_status groups internal changes and deletions under the nearest directory outline, showing directory names and counts. See directory outlines. Nested Git repositories are scanned separately and combined, as described in the file scope section.

Optional: CBM call graph

Install codebase-memory-mcp and add it to your agent's PATH to enable affected-file suggestions based on call relationships. Install only its binary, without registering another MCP server:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --skip-config
command -v codebase-memory-mcp

A new agent session starts the daemon and builds the graph automatically. You can also run ortg graph in the target repository to warm it up. Core outline features continue to work when CBM is absent or unavailable. Set ORTG_CBM=off to disable it.

Upgrade CBM with codebase-memory-mcp update, then restart the agent session. See the detailed rules for refresh and query behavior.

FAQ

  • The plugin is installed, but nothing happens. Repositories without ortg.tsv stay inactive. Explicitly ask the model to initialize outlines, or run ortg scan.
  • How do I disable ORTG for a repository? Create an empty ortg.disable in the repository root or Git top level. Remove it and start a new session to re-enable ORTG.
  • Large outlines are truncated. Check Codex's context window, tool_output_token_limit, and host settings. Restart and ask the model to retrieve modules separately; do not use incomplete outlines.
  • The table is corrupt or its format is unknown. Preserve the current file before inspecting and restoring ortg.tsv.bak. Upgrade ORTG first if the format is newer. Legacy migration preserves ortg.tsv.old. See format and backups.
  • What are the Windows limitations? PowerShell and CRLF are supported. Background-test Stop reminders require /proc and are unavailable on Windows; a custom CODEX_HOME must be forwarded explicitly. Support has been checked with cross-compilation and Linux tests, but has not been fully validated on Windows hardware. See Windows support.

More documentation

The detailed references below are currently in Chinese:

Author and license

Author: Fei ding.

Released under Apache License 2.0; see LICENSE. You may use, modify, distribute, and use the software commercially. Redistributions and derivative works must retain LICENSE and the copyright and author attribution in NOTICE, as required by Section 4.

Reviews (0)

No results found