organon

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 and the web, 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.

web fetch — Web pages

Fetch and navigate web pages with heading-based structure. Same --tree / -s pattern.

web fetch https://docs.example.com --tree     # heading tree with IDs
web fetch https://docs.example.com -s bK      # read a section
web fetch https://docs.example.com            # read full page

web — Web search

Search the web and return results.

web "tree-sitter Go bindings"

web docs — Library documentation

Resolve library names to Context7 IDs and fetch documentation.

web docs resolve react       # list matching libraries with IDs
web docs fetch /reactjs/react.dev hooks  # fetch docs for a library
CONTEXT7_API_KEY=... web docs resolve react  # with API key (higher rate limits)

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-web

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 runs GitHub PR and Git network operations through its local daemon. 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.

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

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 the daemon:

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

make install
og daemon restart
og daemon health

Clone URLs through the daemon 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> and register an alias plus remote. Reference clones derive ~/code/references/<host>/<owner>/<repo> and remain unregistered. 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 create, og pr view, og pr checks, and og pr comment. 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 daemon logs 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. Restart the daemon, 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 the daemon 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, restart the daemon, verify all owners with og auth status, and then revoke and remove the old key. Before PAT revocation, rollback means reinstalling the previous og binary and restarting its daemon 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

project, og, web, skill, and src each provide a typed stdio MCP server. Configure them as separate processes so clients can grant only the tools a session needs:

{
  "mcpServers": {
    "organon-project": { "command": "project", "args": ["mcp"] },
    "organon-og": { "command": "og", "args": ["mcp"] },
    "organon-web": { "command": "web", "args": ["mcp"] },
    "organon-skill": { "command": "skill", "args": ["mcp"] },
    "organon-src": { "command": "src", "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 daemon must already be running and owns Git, registration, policy, and forge credentials.

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.

src mcp exposes only symbols and read. Both require an exact registered project alias and repository-relative file path. symbols returns code symbols or Markdown sections with IDs; read accepts one ID or a bounded UTF-8 byte range. The server follows symlinks only when they remain inside the registered project and rejects source files larger than 16 MiB before reading. It has no mutation tools and requires no revision or SHA argument.

og mcp exposes twelve tools: auth status, clone, push, pull, PR create/find, and PR get/modify/comment/checks/log/failures. It mirrors CLI current-branch workflows against 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. Restart the daemon after changing og.toml; restart web MCP after changing web configuration. Run <tool> mcp --help for each server's tool list and configuration details.

Why

AI agents that work via shell commands (like logos) can't do multiline file edits. Every existing edit tool uses structured JSON parameters — {"old_text": "...", "new_text": "..."} — 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/web@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/project@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
│   ├── web    ← web search and page reading
│   ├── skill  ← skill discovery
│   ├── project ← registered project discovery
│   └── og     ← 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 uses a local credential-owning daemon.
• 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 and the web.

License

Apache-2.0