ortg
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.
ORTG — 单文件纲要引擎:为 Claude Code / Codex 维护一份与代码对齐的全仓库纲要,改多文件前先写计划并核对
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 installerOpen 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.
- Make single-file changes directly. For multiple files, write target outlines and review the plan with
ortg_reviewfirst. - After changing each file, submit its outline with
ortg_updateand check affected files. - 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.tsvstay inactive. Explicitly ask the model to initialize outlines, or runortg scan. - How do I disable ORTG for a repository? Create an empty
ortg.disablein 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 preservesortg.tsv.old. See format and backups. - What are the Windows limitations? PowerShell and CRLF are supported. Background-test Stop reminders require
/procand are unavailable on Windows; a customCODEX_HOMEmust 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:
- Rules reference: tool protocols, state, gates, test evidence, and storage details.
- Development guide: code layout, build, tests, and contribution workflow.
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)
Sign in to leave a review.
Leave a reviewNo results found