organon

Structure-aware tools for AI agents, plus small workflow CLIs used in the tta-lab workspace.

Organon provides commands that give logos agents structured perception of code, running inside a temenos sandbox.

$ src main.go --tree
├── [aE] func main()               [L1-L15]
├── [bK] func handleRequest()      [L17-L45]
└── [c3] type Config struct        [L47-L55]

$ src main.go -s bK
func handleRequest(w http.ResponseWriter, r *http.Request) {
    ...
}

$ src replace main.go -s bK <<'EOF'
func handleRequest(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    // new implementation
}
EOF

Commands

src — Source files

Read and edit code, config, and docs by symbol. Tree-sitter parses the file into an AST, assigns each symbol a 2-char ID, and you reference symbols by ID — no text matching, no multiline quoting problems.

src main.go --tree                      # symbol tree with IDs and line ranges
src main.go -s bK                       # read a symbol by ID
src replace main.go -s bK <<'EOF'       # replace a symbol (stdin)
...
EOF
src insert main.go --after bK <<'EOF'   # insert after a symbol (stdin)
...
EOF
src delete main.go -s c3                # delete a symbol
cat <<'EDIT' | src edit config.yaml     # text replace (===BEFORE===/===AFTER===)
===BEFORE===
old text
===AFTER===
new text
EDIT

Supports symbol-aware extraction for Go, Rust, TypeScript, TSX, Python, C, C++, Java, Ruby, JavaScript, and many more via auto-inference. Language is detected from file extension. Markdown uses heading-based sections.

src edit is a text-based escape hatch for files where symbol editing is overkill (config files, unsupported languages, quick edits). It uses exact match with whitespace normalization fallbacks and works on any text file regardless of language support.

skill — Skill discovery

List, find, and read agent skills from project-local and global skill directories.

skill list
skill find "review and repair pull requests" --limit 3
skill get organon-src

nd-playlist — Navidrome playlists as code

Create, update, diff, and export Navidrome playlists through the Subsonic/OpenSubsonic API.

nd-playlist ping
nd-playlist search --json "小半 陈粒"
nd-playlist resolve playlists/navidrome/night.yaml
nd-playlist diff playlists/navidrome/night.yaml
nd-playlist apply --dry-run playlists/navidrome/night.yaml
nd-playlist apply --yes playlists/navidrome/night.yaml
nd-playlist export "Mandopop: Soft Night" > playlists/navidrome/mandopop-soft-night.yaml
nd-playlist export-all --output playlists/navidrome
nd-playlist radio diff playlists/navidrome/radios/cliamp.yaml
nd-playlist radio apply --yes playlists/navidrome/radios/cliamp.yaml
nd-playlist radio export > playlists/navidrome/radios/stations.yaml

Default config lives at ~/.config/nd-playlist/config.toml:

server = "https://music.example"
username = "ooneil"
password = "..."

--server, --username, --password, NAVIDROME_URL, NAVIDROME_USER, and NAVIDROME_PASS override local config. If no password source is configured and stdin is a terminal, nd-playlist prompts for the password. Playlist YAML exports include song IDs but never include secrets.

Radio YAML uses name, stream_url, and optional homepage_url. radio diff matches stations by stream URL and radio apply --yes creates only missing stations. Keep machine-owned station files under playlists/navidrome/, which is ignored by Git. Navidrome requires an admin account for this global change.

og — guarded forge operations

og issue reads GitHub and Forgejo repository issues without depending on the checkout branch:

og --project organon issue list --state open --page 1 --per-page 30
og --project organon issue search "credential broker" --state all
og --project organon issue get 42 --json
og --project organon issue comments 42 --page 2

Writes are typed-MCP-only: issue_create, issue_update_title, issue_replace_body, issue_edit_body, and issue_comment. Creation requires both title and body (the body may be empty); title, whole body, exact batch body edits, and comments are independent. Exact edits match each old text once in the body just fetched, reject duplicate/missing/ambiguous/overlapping or no-op edits before one body update, and preserve all other Markdown bytes. They do not provide remote compare-and-swap: a simultaneous remote edit can race. List defaults to open, search to all; pagination defaults to page 1 / 30 items and accepts at most 100. Comments are oldest first. Provider search ranking and tokenization differ, and neither uncertain creates nor comments are retried.

og runs GitHub PR and Git network operations directly inside the calling CLI or MCP process. GitHub authentication uses repository-scoped installation tokens minted by a GitHub App; GITHUB_TOKEN, GH_TOKEN, and github_token_env are not used. Forgejo continues to use its existing token environment variables.

Controlled og Git transport honors only a supported user-global http.version value (HTTP/1.1 or HTTP/2); all other global and system Git configuration remains isolated. To select HTTP/1.1 for a proxy path with HTTP/2 framing failures, run:

git config --global http.version HTTP/1.1

This is a transport preference for HTTP/2 framing failures, not a fix for TCP 443, TLS handshake, proxy-node, routing, or forge availability failures. No API/MCP schema, deployment, or secret-handling behavior changes with this exception.

Pull-request merging is approval-gated through Impri. Configure the optional operator-owned section in the existing ~/.config/ttal/og.toml; the API key is never accepted by a tool request or shown in output:

[impri]
base_url = "http://impri.localhost:17480"
api_key = "im_..."

Organon reads this optional section only from og.toml; there is no Impri environment-variable fallback or second configuration file.

og pr merge --dry-run --pr-id 123 --json submits an immutable git.merge_pr action containing the provider, forge, repository, PR number, head branch, head SHA, base branch, squash method, and execution mode. The structured result includes the action ID and Impri inbox URL. An operator approves or rejects the card in the web inbox; agents may use --wait --timeout 30s and repeat the same project, PR ID, and mode request to recover the action. The returned action ID is audit/web identification only, not an input. Dry-run approval records a mock merge without changing the forge. Real mode uses the same gate, then refetches the PR and CI and requires an open, mergeable PR at the approved head SHA with CI state success or not_configured before a squash merge. pr_checks exposes that machine state; for not_configured it also explains that merge policy allows proceeding without checks. For GitHub, not_configured specifically means the Checks API returned zero Check Runs; legacy commit-status integrations are outside this gate. Pending, rejected, expired, timed-out, malformed, stale, and failed actions do not merge. Provider/network/API availability failures leave an approved action retryable; repeat the same request without new approval. Deterministic guard or executor failures end the approved action as terminal execute_failed; this does not mean the PR can never merge, only that a later attempt needs new approval. A rejected or expired action is automatically replaced when the same request is repeated, even if the immutable PR snapshot is unchanged. A successful attempt is reported as executed; real mode then records the receipt, fast-forwards the registered single-checkout default branch, and removes only local and origin head refs that still match the approved SHA. Dry-run performs no checkout switch, pull, or branch deletion. If receipt reporting fails, the response identifies the merged outcome and a repeated request repairs the receipt without merging twice. If cleanup fails after the receipt, the response remains executed with a secret-free cleanup_error, retryable=true, and next_action=retry_same_request. Repeat the exact same project, PR, and mode request; the forge merge is already complete and must not run again. Completion requires the executed receipt, successful default-branch pull, and absence of matching approved head refs. If Impri approval GET or wait polling is temporarily unavailable, the result is the local unavailable state: no forge call was made, and the same request is retryable. If an execute_failed receipt cannot be recorded, the result stays approved and retryable; repeating the request revalidates and reports the deterministic failure rather than pretending Impri accepted it.

Automatic cleanup supports the registered normal single-checkout workflow. It refuses dirty or unrelated checkouts and any local/remote head ref that moved away from the approved SHA; worktree coordination is outside this version and normal Git worktree refusal remains an error. og pull remains available for its existing guarded closed-PR workflow, but is not a second step after a successful real merge. Telegram, webhooks, a daemon, and Impri API-key provisioning or rotation are outside this version. The final operator PoC uses the configured deployed Impri instance, a web-approved dry-run card, and no real merge.

Create the real App only after both implementation PRs are merged, green, and the merged binary is ready to install. Register one App under a stable GitHub account and allow it to be installed by the other managed accounts. It needs no Marketplace listing, OAuth flow, callback, webhook, or organization permission. Grant only these repository permissions:

• Contents: read and write
• Pull requests: read and write
• Checks: read-only
• Actions: read-only
• Workflows: read and write
• Issues: read and write

Install it on selected repositories only in tta-lab, GuionAI, and LamplitIsles. Each installation owner must approve the permissions. Do not grant Administration, Members, Secrets, Deployments, or other organization access.

Before testing writes, configure every managed default-branch ruleset to require a PR and required checks, restrict updates, and disallow force pushes and deletion. Keep the App out of every bypass list. og can reach main and its App token has Contents write permission, so GitHub rulesets are the hard merge and default-branch boundary.

After downloading a private key, keep it outside the repository and configure OG:

install -d -m 700 ~/.config/ttal/og
install -m 600 ~/Downloads/your-app.private-key.pem \
  ~/.config/ttal/og/github-app.pem
cat <<'EOF' > ~/.config/ttal/og.toml
[github_app]
app_id = 123456
key_source = "file"
key_ref = "og/github-app.pem"
allowed_owners = ["tta-lab", "GuionAI", "LamplitIsles"]

[forgejo]
allowed_base_urls = ["http://forgejo.localhost:17480"]
EOF
chmod 600 ~/.config/ttal/og.toml

Before replacing a pre-direct-execution installation, stop and remove its user service with the old installed binary. On macOS:

OLD_OG="$HOME/.local/bin/og"
SERVICE="gui/$(id -u)/io.guion.og.daemon"
"$OLD_OG" daemon stop || true
"$OLD_OG" daemon uninstall || true
launchctl bootout "$SERVICE" 2>/dev/null || true
if launchctl print "$SERVICE" >/dev/null 2>&1; then
  echo "old og service is still running; stop it before upgrading" >&2
  exit 1
fi
rm -f "$HOME/Library/LaunchAgents/io.guion.og.daemon.plist"

On Linux:

OLD_OG="$HOME/.local/bin/og"
"$OLD_OG" daemon stop || true
"$OLD_OG" daemon uninstall || true
systemctl --user stop og.service 2>/dev/null || true
if systemctl --user is-active --quiet og.service; then
  echo "old og service is still running; stop it before upgrading" >&2
  exit 1
fi
rm -f "$HOME/.config/systemd/user/og.service"
systemctl --user daemon-reload

The direct-execution release has no daemon lifecycle commands; run this cleanup before replacing the old binary.

make install
og auth status --project organon

Clone URLs through OG so destination, authentication, and registration stay on one boundary:

og clone organon
og clone https://github.com/tta-lab/organon.git
og clone --alias forgejo https://codeberg.org/forgejo/forgejo.git
og clone --reference https://github.com/modelcontextprotocol/go-sdk.git

Alias clones use the registered path and canonical remote. URL project clones derive ~/code/projects/<owner>/<repo> with lowercase owner and repository directory components and register an alias plus remote. Reference clones derive ~/code/references/<host>/<owner>/<repo> with the same lowercase owner and repository directory components and remain unregistered. The local path is distinct from provider-specific repository identity, whose remote spelling is preserved. Only GitHub, configured Forgejo roots, and anonymous generic HTTPS are supported; callers cannot provide a destination or credentials.

For registered operations, projects.toml is the repository identity SSOT. Immediately before a Git network operation, og checks the effective fetch URL and, for writes, every push URL against that remote before resolving a token. Normal repository hooks such as Lefthook run without bypasses.

Archived project entries remain useful context. They may read PR/CI state and fast-forward the known default branch with og pull, but cannot push, tag, create/modify/comment on PRs, or run pull's branch-cleanup path.

Keep the migration PAT active during rollout. In one selected repository from each owner, run og auth status and require every permission to report ready. Then use a disposable feature branch to verify og push, og pr view, og pr checks, and og pr comment. Verify pull-request creation and modification through the typed MCP pr_create/pr_modify tools. Confirm GitHub attributes the push and PR activity to the App bot. Also verify that an SSH-configured origin is unchanged on disk, an uninstalled managed write fails without fallback, and a third-party public repository can pull anonymously but cannot write. Inspect command errors and local Git configuration for credential material without printing any secret values. Remove the downloaded key copy after this passes; GitHub can issue a replacement, so no private-key backup is required.

Only after all three owners pass, remove local github_token_env keys and GitHub PAT variables from ~/.config/ttal/.env and shell startup files. Run the command again, repeat a representative App-only push and PR check, and then revoke the migration PAT.

Installation tokens are automatic, memory-only, repository-scoped, and expire after about one hour. The App private key is long-lived: it must never enter an agent environment or Git child process. Direct git, gh, and arbitrary API calls are outside OG's credential boundary and may still use personal credentials; mandatory GitHub rulesets protect the default branch in those paths.

For key rotation, create a replacement App key, install it with mode 0600, run og auth status again, verify all owners, and then revoke and remove the old key. Before PAT revocation, rollback means reinstalling the previous og binary and stopping and uninstalling the old service with the existing migration PAT. After revocation, emergency rollback requires a new narrow temporary PAT; never reactivate or reuse the exposed migration PAT.

MCP servers

og and skill provide typed stdio MCP servers. og mcp combines local project discovery with guarded forge workflows; project discovery works without forge credentials or network availability:

{
  "mcpServers": {
    "organon-og": { "command": "og", "args": ["mcp"] },
    "organon-skill": { "command": "skill", "args": ["mcp"] }
  }
}

Use project_get or project_list to discover the exact five-field project record: alias, name, path, canonical remote, and archive state. Active aliases are single-layer names and cannot contain dots. Project registry updates are visible on the next MCP call. The repository-oriented og tools accept only that alias; they do not accept a filesystem path, working directory, MCP root, file URI, or credential. clone accepts a URL instead. The og MCP process initializes configuration on its first forge call, then retains Git, registration, policy, credentials, or that initialization error for its lifetime.

skill mcp exposes skill_list, skill_find, and skill_get. With no project argument it searches only global skill directories. With an exact registered alias, project-local skills take priority over global skills. Results use stable source labels such as project:.agents instead of discovery-root paths. skill_find accepts one natural-language query and an optional limit, then ranks token matches across skill names, descriptions, and categories. The CLI skill find command uses the same query validation, defaults, limits, and ranking behavior. Individual SKILL.md files larger than 1 MiB are rejected before parsing.

og mcp exposes typed project discovery, auth, clone, push, pull, PR create/find, PR get/modify/comment/checks/log/failures, and approval-gated pr_merge. Create and modify are typed MCP-only because their user-controlled title/body fields may contain multiline free text; exposing those bodies through shell CLI arguments would reintroduce quoting and escaping ambiguity. pr_merge remains available through both typed MCP and og pr merge because its inputs are structured short scalar flags; agents should default to MCP, and both adapters call the identical Impri approval-gated domain operation.

Merge callers consume the structured result fields status, retryable, next_action, completion, detail, action_id, inbox_url, receipt_error, cleanup_error, and snapshot. The action_id is audit/web identification only. Surface the inbox and wait for pending actions; retry_same_request means repeat the exact same project, PR ID, and mode request; treat executed with no receipt or cleanup error as complete. Repeating the same request after rejection or expiry creates a replacement approval, while terminal execution failure ends only that approval action and needs new approval for a later merge attempt. The local unavailable status means approval state is unknown, no forge call was made, and the same request is retryable. An executed result with receipt_error uses repair_receipt and is repeated only to repair the Impri receipt, never to merge again. An executed result with cleanup_error uses retry_same_request; it reports that the forge merge is complete and cleanup must finish without another forge call. Completion means executed with neither receipt nor cleanup error. MCP current- branch workflows use the registered checkout's current branch. Force push uses force-with-lease and is rejected on the default branch. Pull retains the CLI's guarded closed-PR branch cleanup. A positive PR ID selects a branch-free remote operation; pr_get, modify, comment, checks, log, and failures use the current branch when the ID is omitted. Tag remains CLI-only. Start a new og process after changing og.toml. Run <tool> mcp --help for each server's tool list and configuration details.

Pi extensions

Pi's only native Organon package is @tta-lab/pi-src, which replaces Pi's built-in read and edit with symbol-aware operations and exact multi-edit batches. Pi accesses project discovery and forge workflows through its existing og mcp integration; Organon does not ship a Pi bridge for those tools. See pi/README.md for pi-src installation, platforms, development, and release guidance.

Why

AI agents that work via shell commands (like logos) can't do multiline file edits. Every existing edit tool uses structured JSON parameters — {"path":"file","edits":[{"oldText":"...","newText":"..."}]} — which requires a tool-calling protocol, not shell.

Organon solves this by replacing text matching with symbol targeting. The LLM doesn't need to reproduce the old code — it asks for the symbol tree, picks an ID, and pipes the new code via a single heredoc. One stdin arg instead of two JSON fields.

Install

Homebrew

brew install tta-lab/ttal/organon

From source

CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/src@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/skill@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/og@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/nd-playlist@latest

From release

Download binaries from GitHub Releases.

How it fits

temenos (sandbox)
├── organon tools (pre-installed)
│   ├── src    ← structure-aware file read/edit
│   ├── skill  ← skill discovery
│   └── og     ← project discovery plus guarded Git and forge operations
├── standard tools (cat, ls, grep)
└── user code

logos (agent loop)
├── LLM writes: $ src main.go --tree
├── temenos executes in sandbox
├── output fed back to LLM
└── LLM writes: $ src replace main.go -s bK <<'EOF' ... EOF

Design

• Small cores, thin adapters — CLI and MCP commands share typed internal services instead of duplicating business rules. Most commands parse, act, and exit; og composes its credentials and policy in the calling process.
• Stdin for content — new code goes through heredoc. One multiline arg, not two.
• 2-char IDs — base62 identifiers for symbols/sections, same system as flicknote.
• Tree-sitter — syntax-level AST parsing. No LSP server needed.
• Language detection — from file extension. No --language flag.

The name

Aristotle's Organon (ὄργανον, "instrument") was his collected works on logic — the toolkit that made reasoning possible. These tools are the instruments through which logos reasons about code.

Project	Role
temenos	The boundary — sandbox isolation
logos	The reason — agent loop
organon	The instruments — perception and action

License

Apache-2.0