DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

tta-lab /

tta-lab/organon

Topic repository only

Structure-aware tools for AI agents. Tree-sitter code editing, web page navigation, search. No daemon, no JSON, just stdin.

★ 5 Stars1 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@201c934e

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.

pr_edit_body is the typed MCP counterpart to issue_edit_body, using the same exact oldText/newText batch envelope:

{
  "project": "orga",
  "pr_id": 123,
  "edits": [
    {"oldText": "Old paragraph\n", "newText": "New paragraph\n"},
    {"oldText": "Obsolete paragraph\n", "newText": ""}
  ]
}

For an issue, call issue_edit_body with issue_id instead of pr_id. Omit pr_id to target the current branch's PR; an explicit positive ID works without a current branch. Both tools require a nonempty batch and nonempty, unique original-body matches; empty newText deletes. PR edits preserve the title and comments. An uncertain write is not automatically retried; a provider error after writing does not guarantee rollback.

og runs GitHub PR and Git network operations directly inside the calling CLI or MCP process. Configure exactly one GitHub mode: an owner-scoped fine-grained PAT or a GitHub App. GITHUB_TOKEN, GH_TOKEN, and github_token_env are not used. Forgejo continues to use its token environment variables. GitHub merge and CI queries are unsupported in both modes; GitHub PR view omits CI. Forgejo keeps merge and CI status, while CI logs and failure details are outside og.

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 honors the global operator-owned merge.approval policy in ~/.config/ttal/og.toml through both CLI and typed MCP. Omitted policy defaults to impri; impri, none, and deny apply to Forgejo, with no per-project overrides. GitHub merge is always rejected, including dry-run. To reject merge requests, including dry-run, before contacting Impri or a forge, configure:

[merge]
approval = "deny"

The rejection is non-retryable while deny remains configured. No Impri section is required; if present, it is still validated. This policy governs merges requested through og; forge permissions remain separate.

For direct execution, configure:

[merge]
approval = "none"

Under none, requesting a merge immediately runs the existing guards and expected-head squash operation without initializing or contacting Impri. No Impri section or credentials are required, and no notifications are sent. An explicit Impri section is still validated as part of the complete config file. --wait and --timeout retain their argument validation but do not wait under none; they control approval waiting only under impri.

Direct results identify approval_policy=none. blocked is retryable with next_action=retry_same_request for pending or unverifiable CI and temporary provider/checkout failures. CI failure/error, a closed-unmerged or nonmergeable PR, or identity changes during the request return terminal failed with next_action=none; resolve the reported condition before a fresh request. CI success or not_configured permits execution. Remote trust, provider support, immutable expected head, forge protections, and safe checkout checks still apply. A subsequent request snapshots the current PR anew.

An executed direct result has no action ID, inbox, or receipt. Real execution pulls the registered default branch and removes matching local/origin head refs. If cleanup fails, it stays executed with cleanup_error and next_action=retry_same_request. Retry with the same project, explicit PR ID, and mode: observing the PR as merged resumes cleanup without a second forge merge, including after an uncertain provider response. Completion requires executed with no cleanup error. Direct dry-run uses the existing mock executor without forge mutation or checkout switch, pull, or deletion; it is not an expanded preflight check.

Under the default impri policy, merging is approval-gated. 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. 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.

GitHub authentication setup

Choose one section in ~/.config/ttal/og.toml: [github_pat] or [github_app]. Configuring both is an error. PAT mode uses exactly one resource owner, checked before reading credentials. Out-of-owner Git clone and pull may proceed anonymously for public repositories; writes and API operations are rejected. In-scope authentication failures never fall back to anonymous access or an App. App mode retains its allowed-owner and repository-scoped installation token behavior.

To create a fine-grained PAT, open GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token. Choose a name and expiration, select the organization or user as Resource owner, and select only the repositories og needs. Request the repository permissions below. The token cannot exceed the creator's own repository access. An organization may block PATs, restrict expiration, or require owner approval; a pending token can only read public resources until approved. See GitHub's token instructions and organization policy.

Repository permission Read-only use Write use
Contents Read for clone and pull Read and write for push and tags
Pull requests Read for PR lookup and details, and for private active non-default-branch pulls Read and write for PR creation and edits
Issues Read for issue lookup and comments Read and write for issue writes and comments; PR comments use the issues API
Workflows Not needed Read and write only when pushing changes to .github/workflows
Metadata Read (automatically included) Read (automatically included)

For a private repository, pulling the default branch requires Contents read. Pulling an active non-default branch also requires Pull requests read: og looks up the branch's PR to detect a closed PR before pulling or cleaning up. GitHub's PR list and PRs associated with a commit endpoints both require that permission for private resources. GitHub's fine-grained REST permission table documents the endpoint requirements. Checks and Actions permissions are not needed by og. If an operation is unused, omit its permission. Branch rules and organization policy still govern writes.

Store the token in a private file outside the checkout; do not put it in shell history, command arguments, environment variables, URLs, Git config, logs, or agent messages. Create a 0700 directory and a current-user-owned regular 0600 file, then paste the token into that file using a private editor. The file must not be a symlink and contains only the token, optionally followed by one newline. One way to create it without placing the token in a command is:

umask 077
install -d -m 700 ~/.config/ttal/og
${EDITOR:-vi} ~/.config/ttal/og/github-pat # paste and save the token privately
chmod 600 ~/.config/ttal/og/github-pat

For example, with the token privately placed in ~/.config/ttal/og/github-pat, configure:

[github_pat]
owner = "example-org"
token_file = "og/github-pat"

[forgejo]
allowed_base_urls = ["https://forge.example.com"]

Relative token paths are resolved against the directory containing og.toml. Restart a running MCP server after changing the config. og auth status --project <alias> checks owner and file accessibility but does not validate the token with GitHub or prove permissions; its PAT ready field is false. Verify access with a permitted read such as og pr get <number> --project <alias>. A 401 or 403, or a private repository appearing absent, can mean expiry, revocation, missing selected repository/permission, or organization approval/policy. Check those settings without printing the token. For rotation, create and approve a replacement with the same intended scope, replace the protected file, verify a read, then revoke the old token. og reads the file for each operation.

For multiple owners, configure a GitHub App instead (not alongside PAT):

[github_app]
app_id = 123456
key_source = "file"
key_ref = "og/github-app.pem"
allowed_owners = ["example-org", "another-org"]

Install the App on selected repositories and obtain owner approval. For the full retained feature set grant Contents, Pull requests, and Issues read/write; Workflows read/write is optional for workflow-file pushes. App private keys use the same private directory and file protections. og auth status checks App installation permissions; it does not require Checks, Actions, or optional Workflows. Installation tokens are repository and purpose scoped and are kept in memory. GitHub's own rulesets remain the default-branch boundary.

Clone URLs through og so destination, authentication, and registration share one boundary: og clone <registered-alias> or og clone --reference https://github.com/owner/repo.git. Registered project remotes are verified against Git's effective fetch and push URLs before credentials are resolved. Archived projects can read and fast-forward their known default branch but cannot push, tag, mutate PRs, or perform branch cleanup.

MCP servers

og and skill provide typed stdio MCP servers. og mcp combines local project discovery, read-only source search/inspection, and guarded forge workflows. Project discovery and source inspection work 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 project references, but not a filesystem path, working directory, MCP root, file URI, or credential. Source tools also accept an absolute path exactly equal to a registered checkout; their file paths must remain within that checkout. 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, read-only source_list, source_search, source_symbols, source_read, repo_status, repo_commits, repo_compare, and repo_diff, plus auth, clone, push, pull, PR create/find, PR get/modify/comment/checks/log/failures, and policy-controlled pr_merge. source_search(project, pattern, limit?) accepts a ripgrep regular-expression pattern as one argument; Organon controls all rg flags and the registered checkout root. repo_diff(project, path?) returns the tracked unified diff from the local default-branch merge base through the working tree, along with file summaries and untracked paths. It does not fetch, and it bounds the patch to the standard tool-output limit. source_list browses direct children of a directory; repo_status separates staged, unstaged, untracked, and conflicted paths. repo_commits lists HEAD or local origin default-branch history, and repo_compare compares two full commit IDs without including working-tree changes. 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 shared merge domain operation.

Merge callers consume approval_policy independently of snapshot.execution_mode, and the structured result fields status, retryable, next_action, completion, detail, action_id, inbox_url, receipt_error, cleanup_error, and snapshot. Direct policy omits approval metadata and uses blocked, failed, and executed as described above. The remaining approval lifecycle guidance applies to approval_policy=impri. 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

og mcp source search and make test require ripgrep (rg) on PATH. Install it with brew install ripgrep on macOS or sudo apt-get install ripgrep on Debian/Ubuntu.

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

—/ 5

No ratings yet

Manifest verification required

Commit 201c934eed34

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout