sofia

sofia

SF (Sophia Foundation / Source Fabric) — a Go toolkit of CLI tools and AI-agent instructions for working on software projects.

• Agentic Tools — Go binaries the model calls to take actions.
• Context Providers — Go binaries that collect compact context from code/git and hand it to the model as TOON.

Architecture and design rationale — PLAN.md.

Requirements

• Go ≥ 1.24 (this repository is tested on 1.25)
• Linux/macOS, shell — Fish or Bash (for completion)

Build

bash scripts/build.sh            # every binary into bin/** (one per tool)
# → bin/sf                              master CLI with all subcommands
# → bin/common/<tool>                   standalone binaries: grep, gripe, cc, code, changed,
#                                         doctor, composer, packagist, github, vue, worktrees

Install onto $PATH (symlink ~/.local/bin/sf, no shell aliases needed):

make install     # build + ln -s bin/sf → $BINDIR (default ~/.local/bin)
                  # + regenerate bash/fish completion (kept in sync with the binary)

make install also refreshes shell completion (~/.config/fish/completions/sf.fish and ~/.local/share/bash-completion/completions/sf), so it always matches the current command tree. Regenerate just the completions with make completions.

Update an already-installed sf:

make update      # git pull --ff-only + rebuild + regenerate completions

make with no target prints self-documented help for every target.

Usage

A single entry point — sf (built on Cobra) — or a dedicated standalone binary; they're equivalent:

# via the master CLI
./bin/sf grep --root=/path/to/project --ext=php "DeleteUser"

# directly (equivalent)
./bin/common/grep --root=/path/to/project --ext=php "DeleteUser"

sf grep — cross-project search with enclosing context

Cross-project TOON-grep for arbitrary searches (a class name, a chunk of SQL, a regex): layered output with the enclosing function/class attached to every hit, so a bare match comes with the context needed to understand it.

sf grep --root=/path/to/project --ext=php "DeleteUser"
sf grep --root=/path/to/project --ext=php --regex '#\[Route\('
sf grep --case=false --ignore-dir=storage 'TODO'

By default the pattern is matched as a substring (like grep), so the stem techno matches technology; --word restricts to whole-word matches. Flags: --regex (Go regexp), --ext php,ts,vue, --ignore-dir extra,paths, --root, --case, --word (literal mode only), --max-per-pattern N, the common --md/--json aliases. Default ignores: vendor, node_modules, var, .git, dist, build, target, __pycache__, IDE directories.

sf refs — who defines/uses a symbol, with enclosing context

sf refs <symbol> answers "who defines/uses this symbol across the tree, and from where" in one call — grep -rn <symbol> plus opening every caller by hand to see what function it's in, folded into a single deterministic scan (Go/PHP/TS/TSX/Vue by default). Every hit is labeled def or use (textually — a name declared in several places shows several defs) and carries its enclosing function/type: AST-derived for Go, the same regex heuristics sf grep uses for PHP/TS/Vue.

sf refs Handle                 # who defines/calls Handle, across the tree
sf refs deleteUser --ext php   # PHP only
sf refs Enclosing --max 0      # widen past the default 30-hit cap

Matching is literal and word-boundary-forced (not regex — <symbol> must be a bare identifier). Output is sorted defs-first, then by file, then by line; capped at 30 hits by default (Defs/Uses in the header are always the true totals, even when the list is capped) — --max 0 for every hit, a negative --max to remove the cap entirely.

Measured on this repo's own tree (docs/measurements/tools/refs.md).

sf code — structural summary of a source file (Go + PHP + TS/Vue)

A compact structural summary of a file without function bodies: for Go — package, imports, types (struct fields + tags, interface methods), function and method signatures, const/var; for PHP — namespace, class/interface/trait/ enum, extends/implements, attributes (#[ORM\…]/#[Route]/#[IsGranted]), constructor dependencies, properties, method signatures; for TS/Vue — imports, top-level declarations, members of interface/type/enum, and for .vue — the component, defineProps/defineEmits/defineModel, stores and API calls it uses, and the components referenced from <template>. It replaces cat-ing a whole file when what's needed is shape or API — which is exactly where read tokens go.

Go uses the stdlib go/parser. PHP uses a shared parser with 8.2–8.5 syntax normalised down to the 8.1 grammar it understands (covers >99.5% of real files). TS/Vue use a line-based extractor (approximate; there's no good pure-Go TS parser).

sf code is a thin router: it dispatches by extension to per-language libraries under internal/common/code/{gocode,phpcode,tscode} (each tested in isolation), runs multiple files in parallel, and aggregates the result. Pass a list of files: sf code a.go b.php api/types.ts. Or <file> <symbol...> to slice one or more symbols (the source of each function/method/type; Go and PHP) instead of the whole file — a symbol that isn't found doesn't fail the others, it's just noted as missing. Invariant: compact-or-raw — if a file can't be parsed, or the summary isn't shorter, the full file is returned (== cat), never an error, so sf code is safe to run on anything.

Below 8 KB the tool skips structure entirely: the raw file comes back behind a one-line # raw: … header (per file inside a batch; in slice mode the whole file, with the requested symbols noted as included). The project's own A/B measured structural round-trips losing to a plain read on small files, so sf code is never worse than cat — "always use sf code" is a safe rule. SOFIA_CODE_RAW_BELOW=<bytes> moves the threshold; 0 disables the passthrough.

Every code/grep/refs/changed call ends with a one-line cost footer — e.g. # sf ≈612 tok · raw ≈3120 · saved ≈2508 — so the per-call token economics are visible to the agent itself; SOFIA_FOOTER=off hides it.

--api (PHP): the effective public surface of a class — its own methods plus methods from use-d traits (recursively) plus inherited ones from extends, each with a via column naming its source. One call instead of find vendor | grep/cat-ing traits and parents by hand; resolved via PSR-4 (the class's own namespace plus vendor/composer/autoload_psr4.php), gracefully falling back to # unresolved for anything it can't resolve. --exported on a class with traits/a parent adds a one-line hint pointing at --api.

sf code internal/server/server.go
sf code frontend/src/api/types.ts frontend/src/views/ProductsView.vue  # several at once
sf code src/User/Entity/User.php --exported    # public API only
sf code vendor/acme/lib/src/FluentThing.php --api  # the full surface: traits+inheritance
sf code internal/server/server.go Server.Routes  # slice of a single method
sf code internal/cc/cc.go Parse ingestEntry      # slice several symbols at once

Measured: Go 6–23×, PHP 2–20× (--api over traits/inheritance ~10×), TS/Vue ~6–14× against cat (docs/measurements/tools/code.md).

sf vue routes — vue-router route map

sf vue routes --root /path/to/frontend               # finds router/index.ts
sf vue routes frontend/src/router/index.ts --md

Parses createRouter({ routes: [...] }) into a flat table {path, name, component, meta} (nested children are flattened onto the parent). The frontend counterpart of a backend routes command. Measured: ~6.3× against reading the router file (docs/measurements/tools/vue-routes.md).

sf changed — classified git diff

A compact diff summary instead of reading the full git diff: per file — status, churn (+/-), category (source/test/config/docs/build/migration), language, and the functions/classes touched (from git's own funcname context, no file parsing), plus per-category totals.

sf changed                 # working tree vs HEAD (+ untracked)
sf changed --staged        # staged only
sf changed HEAD~3          # last 3 commits
sf changed main..HEAD --md

Measured: ~48× against the full git diff (22.7k→0.47k tokens), at roughly the size of --stat, but with classification and touched symbols included (docs/measurements/tools/changed.md).

sf worktrees — cross-project overview of worktree forks

Read-only, cross-project view of git-worktree dev forks under a parent directory (/www by default, override with --www), so every parallel session is visible at a glance. For repos that ship a dev/worktree.sh script, each row is enriched with that script's stack state, health, ports and dirty/ahead flags (via its own ls --json); other repos just show their plain linked worktrees. The tool itself is read-only — create/remove forks through the project's own dev/worktree.sh.

sf worktrees               # all forks (TOON)
sf worktrees --json        # machine-readable
sf wt --md                 # alias + markdown
sf worktrees --www ~/code  # scan a different parent directory

sf doctor — installation health

Not a token tool but insurance against a silent deploy gap: one call checks that the local sf install is current and working.

sf doctor          # TOON checklist; exit 1 if anything fails
sf doctor --json

Checks: staleness — bin/sf older than the git HEAD it's linked from (the classic "fixed it in git but forgot to rebuild" trap, where the agent keeps running the stale binary; core check, fail); path — whether sf on $PATH resolves to the binary that's actually running; completions — whether the fish/bash scripts are installed; claude — whether the claude CLI is available; hook — whether the PreToolUse sf hook pre hook is configured in ~/.claude/settings.json; skill — whether the sf-context skill is installed under ~/.claude/skills/ and not stale; calllog — the resolved log path. A non-zero exit code on any fail makes it a usable gate in a script or make target (docs/measurements/tools/doctor.md).

sf gripe — feedback when sf didn't help

Not a token tool but a feedback channel. It catches the one failure class invisible in calls.jsonl: sf exited 0 but produced the wrong thing, or the agent had to fall back to cat/rg/grep because sf didn't cover the case. Hard failures (non-zero exit) are already in the log and visible via sf history --failed --source agent.

sf gripe 'sf code .kt does not structure it — dumped raw, had to read in full'  # record one
sf gripe                                                                        # list (newest first)
sf gripe --limit 50 --md

An entry is auto-tagged with project, session and time (so the text itself can stay short) and logged like any other call (tool=gripe); a bare sf gripe is a reader for the maintainer and doesn't itself write a log entry. sf doctor surfaces the count of gripes accumulated since the last build, so the loop closes without manual copy-pasting (docs/measurements/tools/gripe.md).

sf hook + skill sf-context — guarding the Read channel

Intercepts the single biggest spend channel: full reads of large source files. A Claude Code PreToolUse hook calls the hidden sf hook pre command: a full Read or bare cat of a .go/.php/.ts/.tsx/.vue file ≥4K is denied once with a hint toward sf code <file> / sf code <file> <Symbol>; an identical repeat call is allowed (so a Read-before-Edit flow doesn't break). Modes via SOFIA_HOOK_MODE: off | suggest | nudge (default) | strict; threshold via SOFIA_HOOK_MIN_BYTES. The pass-through path writes nothing to the log; fired nudges show up under sf history --tool hook.nudge --stats. Fail-open: with no sf on $PATH, sessions behave exactly as before. Configuration (global, ~/.claude/settings.json):

"hooks": {"PreToolUse": [{"matcher": "Read|Bash",
  "hooks": [{"type": "command", "command": "sf hook pre", "timeout": 10}]}]}

The sf-context skill (skills/sf-context/SKILL.md → ~/.claude/skills/, installed by make install) documents the same decision tree — structural read → narrow search → point-read a single body — for any project; sf doctor checks both the hook and the freshness of the installed skill copy. Philosophy and metrics — docs/measurements/tools/hook.md.

sf init — one-shot per-project onboarding

Wires a project up for its coding agents in one pass: a managed sf block in AGENTS.md (markers <!-- sf:begin -->/<!-- sf:end -->, safe to rerun — it replaces its own block in place), the sf-context skill installed into $CLAUDE_DIR/skills, the PreToolUse hook merged into $CLAUDE_DIR/settings.json (backing up the old file to settings.json.sf-bak first), and the sofia MCP server registered in the project's .mcp.json (Claude Code's project-scope MCP config — nothing else installs this yet). The last three steps only fire when Claude Code is actually detected (on the machine and/or in the project); otherwise they're reported as skipped rather than failing the call.

sf init                # full onboarding for the current directory
sf init --project ../other-repo
sf init --check         # dry run: report what each step would do
sf init --force         # also overwrite a hand-edited installed skill
sf init --corporate     # AGENTS.md only — no ~/.claude or .mcp.json writes,
                        # for locked-down environments
sf init --revert        # undo it all; --check combines for a dry run

--revert removes everything init wired: the managed AGENTS.md block (the file itself when it held nothing else), the installed skills, the PreToolUse hooks and the MCP registrations — surgically, leaving every other key, hook and line in those files untouched. The .sf-bak backups are kept rather than restored (they may predate later hand edits); a hand-edited skill copy is left alone unless --force.

Codex CLI is wired the same way, automatically, whenever sf init detects it on the machine (~/.codex or $CODEX_HOME) — the hook and MCP server go into $CODEX_HOME/config.toml, the skill into $HOME/.agents/skills. See docs/codex.md for what that hook does on Codex (no Read tool — reads happen via Bash), manual TOML snippets, and the --corporate story under enterprise lockdown.

sf claude — launch Claude Code for a project

Pairs with sf init: init wires a project up (AGENTS.md, skill, hook, MCP), sf claude launches into it. It's a thin wrapper around the claude CLI — the only binding is running with cwd set to the project dir, so claude loads that project's own root AGENTS.md/CLAUDE.md the normal way. No separate instruction tree, no injected prompt unless you opt in.

sf claude                        # launch claude in the current directory
sf claude myproj                 # launch $SF_CLAUDE_DIR/myproj
sf claude myproj 2               # fork s2 of myproj (needs dev/worktree.sh)
sf claude --dir ~/code/myproj
sf claude myproj --model opus --permission-mode plan
sf claude myproj --task "add error handling to fetchUser in api.js"
sf claude myproj --dry-run       # print the resolved command, don't launch

Project resolution: --dir wins outright; else a bare project name resolves to $SF_CLAUDE_DIR/<project> (the projects root — set it once and every project name resolves under it); with neither, it's the current directory. Set $SF_CLAUDE_PROMPT_FILE to a file of extra system-prompt text if you want claude to see something beyond AGENTS.md; unset, none is added.

A second positional forks the session into an isolated git-worktree copy of the project via that project's own dev/worktree.sh (own branch, own stack), created on first use — a bare number N maps to fork sN.

--task/-t runs claude non-interactively (claude -p) and exits with its status code, for scripting or CI.

sf composer — PHP package tree overview

Compact views over the composer.json files in a tree instead of cat-ing each one by hand (plus git tag and grepping phpstan.neon). Useful for a monorepo or a set of sibling package repos.

sf composer ls /path/to/your/packages   # one row per package: version/type/php/phpstan/scripts/deps/dev
sf composer show array-reader           # one package in detail (scripts with their commands, all deps)
sf composer check enum                  # run the check gate, collapsed to pass/fail
sf composer check --root /path/to/your/packages   # every package

• ls — walks the tree (internal/walker) → TOON {pkg, version (git tag), type, php, phpstan, scripts, deps, dev} (deps = require, dev = require-dev, both without php/ext-*). Measured: ~7.3× against reading 9 composer.json files (docs/measurements/tools/composer-ls.md).
• show — full metadata for one package (by name/dir/path): scripts with their commands, require/require-dev. Measured ~2.6×.
• check — runs each package's check script (test+phpstan+cs) and collapses the verbose output into {pkg, status, exit, dur_ms, fail}. Measured: ~17× per package, ~30× across a whole collection (docs/measurements/tools/composer-check.md).

sf packagist — release status vs Packagist

For every package in a tree: local tag vs whether it's pushed vs the latest version on Packagist → shows what still needs tagging/updating (the webhook doesn't fire for every package).

sf packagist status /path/to/your/packages
sf packagist status --offline /path/to/your/packages   # local tags only
sf packagist release array-reader 2.1.0 --dry-run       # preview a release
sf packagist release array-reader 2.1.0                 # tag+push+update+verify

• status — one row per package: {pkg, local_tag, pushed, packagist, state}; state = in-sync | needs-update | unpublished | no-tags | local-stale. Measured: ~23× against a manual check (git plus parsing 9 p2 documents) (docs/measurements/tools/packagist-status.md). Read-only (HTTP to p2 + git ls-remote).
• release <pkg> <version> — mutating: an annotated tag (reused if it already exists) → push to origin → Packagist's update-package → polling p2 until the version shows up. Token: $PACKAGIST_API_TOKEN, or a per-vendor dotfile under ~/.config/<vendor>/packagist.env. --dry-run prints every step without touching anything; --allow-dirty, --username, --timeout (docs/measurements/tools/packagist-release.md).

sf github — CI runs, PR digest, branch cleanup

sf github ci array-reader --root /path/to/your/packages   # latest runs
sf github ci enum --root /path/to/your/packages --watch    # wait for the final status, one row
sf github ci --root /path/to/your/packages                 # rollup across the whole tree

sf github pr            # your open PRs across all repos + CI status
sf github pr --md       # markdown table (for humans)

sf github branches              # non-default branches across your own repos
sf github branches --delete     # delete branches whose PR is already merged

• ci wraps gh run list/view into TOON {id, workflow, status, conclusion, branch, event, created, title}. The listing itself is roughly 1× on tokens (but scriptable, and resolves a package by name); the real win is --watch: silent polling until the run finishes plus one final row, instead of gh run watch's verbose stream (and a non-zero exit code on failure). When the target is a tree of packages (the root isn't a git repo itself), it prints a per-package rollup — one row per package with its latest run (a pkg column, # failing=K in the header when something's red) — one call instead of looping over packages by hand (docs/measurements/tools/github-ci.md).
• pr — a single gh api graphql call collects every open PR (author:@me + review-requested:@me) across all repos, plus a CI rollup of the head commit and the review decision. TOON {repo, num, ci(✓/✗/⏳/–), review, role, draft, title}; PRs needing action (broken CI / changes requested) sort first. The saving comes from collapsing per-PR gh pr checks into one rollup (like --watch above): 14.7× on a real run, and the ratio grows with the number of PRs and matrix jobs (docs/measurements/tools/github-pr.md).
• branches — lists every non-default branch across your own (non-fork, non-archived) repos with age, the newest associated PR, and a status (merged | closed | open | no-pr); branches safe to delete (PR already merged) sort first. A single gh api graphql call. --delete removes branches whose PR is merged (--delete=closed also removes closed-PR branches); worktree branches are always left for manual removal.

sf cc — Claude Code session analysis

A context provider over the agent's own transcripts (~/.claude/projects/**.jsonl). Unlike sf history (which is about sofia's own calls.jsonl), cc reads Claude Code's own sessions: 2–4 MB of raw JSON compressed into a TOON digest of a few hundred tokens. The project root is resolved from --projects-dir, then $CC_PROJECTS_DIR, then ~/.claude/projects.

sf cc ls                          # session index across all projects, newest first
sf cc ls --project myproject --since 24h
sf cc show last                   # digest of the last session
sf cc show 6bd96fc7                # by session-id prefix
sf cc show myproject               # last session of a project, by name
sf cc resume myproject             # a tiny brief for a cheap session restart
sf cc prompts myproject            # human turns only, in full
sf cc bash myproject --category db # executed commands: deduped, categorised, counted
sf cc candidates --project myproject # tool candidates: what's repeated/expensive
sf cc value                        # weekly $ delta + token-type breakdown, from your own transcripts
sf cc value --quota                # subscription angle: sf's own token savings, last 7 days

A session selector resolves everywhere the same way as an xref lookup: last → id prefix → project name → path.

• show — an on-screen digest: metadata, real token counts from the transcript's own usage records, human prompts (system-reminders, continuation summaries and tool_results filtered out), a tool-call histogram, a bash breakdown by category, files touched, token-heavy results, PRs. Measured: ~400–940× against reading the raw transcript (docs/measurements/tools/cc-show.md).
• ls — a session index with real out/cache tokens; ≈22 tokens/session.
• prompts — human turns verbatim, in order.
• bash — commands deduped + categorised (search/read/git/test/build/db/ fs) + counted; --full for the full text, --min-count/--category.
• candidates — a meta-tool: scans one or many sessions and ranks where the token budget actually goes, by measured tokens: heavy_tools (tokens per tool), repeated_commands, repeated_reads. This is "measure the value before building" as a command — how the next tool candidates get found.
• value — your own weekly $ delta and token-type breakdown, from Claude Code's own transcripts (docs/measurements/tools/cc-value.md). On a flat-fee subscription plan there's no $ to save, so --quota swaps in a different report: it reads sf's own calls.jsonl (not your transcripts) and shows how many output tokens sf handed back to you instead of a raw read/grep/diff, plus the single busiest 5-hour window — the actual unit a subscription's quota resets on.

Output format

Every tool defaults to TOON (Token-Oriented Object Notation) — a compact format built for LLM tokens. The same aliases work across every tool:

sf grep --md   TODO   # equivalent to --format=md
sf grep --json TODO   # equivalent to --format=json

Shell completion

Cobra generates dynamic suggestions: package names, --format values, directories for --root. Both Fish and Bash.

Fish:

./bin/sf completion fish | source                                       # for this session
./bin/sf completion fish > ~/.config/fish/completions/sf.fish           # permanently

Bash:

source <(./bin/sf completion bash)                                                       # for this session
./bin/sf completion bash > ~/.local/share/bash-completion/completions/sf                 # permanently

Once installed, <Tab> works:

sf composer show <Tab>          → array-reader, enum, ...
sf grep --ignore-dir <Tab>      → vendor, node_modules, ...
sf grep --format <Tab>          → toon, md, json

Call history

Every call is written to a JSONL log. The path is resolved by priority:

1. $SOFIA_LOG_DIR/calls.jsonl — explicit override (CI, dev mode).
2. $XDG_STATE_HOME/sofia/calls.jsonl — XDG default.
3. ~/.local/state/sofia/calls.jsonl — fallback (matches the XDG spec's own default).

Every sofia binary (sf and the standalone binaries) writes to the same file, so sf history aggregates the full picture. Every entry is tagged with a source — agent (how Claude invokes it; detected via CLAUDECODE=1 in the Bash tool's environment), manual (typed by hand in a terminal), or test (go test runs never write to the shared log at all). Entries also carry sid — Claude's session id (CLAUDE_CODE_SESSION_ID, matches the transcript filename → joins with sf cc) — and tag — the project (SOFIA_TAG, or the basename of the git root otherwise). Parallel sessions don't interfere with each other: the env is inherited down the process tree, and log writes are atomic.

sf history                                  # last 20 calls
sf history --since 24h --limit 50           # last 24h
sf history --tool grep                      # a single tool
sf history --stats --source agent           # clean agent-only aggregates (no manual/test noise)
sf history --stats --top-inputs 10          # aggregates + top-10 input arguments
sf history --session 6bd96fc7               # one session (same id as `sf cc`)
sf history --tag myproject --source agent   # agent traffic for one project
sf history --adoption --since 7d            # adoption by project × source over a week
sf history --stats --format md              # markdown, for reports
sf history --histogram=hour                 # calls by hour of day
sf history --histogram=day --since 7d       # last week, by day
sf history --clear                          # truncate the log

--adoption aggregates by (project, source): call count, distinct sessions (by sid), errors, failed% and total tokens — which projects actually adopt sf (agent) versus running it by hand.

--stats reports, per tool: call count, errors, total/mean/p50/p95/max duration, total output size, and the top-N most frequent arguments (to spot repeated queries — candidates for caching).

Sample entry

{"ts":"2026-05-21T01:36:00Z","tool":"grep","source":"agent",
 "sid":"fb92295c-9af0-4931-960c-8d0567ec309f","tag":"myproject",
 "args":["--format=toon","DeleteUser"],
 "fp":"0f290d253081ac56","dur_ms":477,"exit":0,"out_bytes":4533,"out_tokens":1180,
 "summary":{"inputs":["DeleteUser"],"queries":1,"total_hits":22}}

Log fields (useful for analysis)

What might get added later

• Cache hits — once tools learn to cache, a cache_hit field in the log.
• Delta between calls sharing an fp — to detect speed regressions.
• Anti-pareto: rarest but slowest fp — optimisation candidates.
• A real tokenizer (tiktoken-go) — the ASCII heuristic currently diverges from actual billing by ±20–30%; fine for trends, not for literal cost attribution.

Packs

sf pack install <git-url|dir> installs a "pack" — a git repo or local directory holding a pack.yaml — laying out everything it declares: sf plugins ($XDG_DATA_HOME/sofia/plugins), Claude skills/commands ($CLAUDE_DIR, env override, default ~/.claude), and project instructions/templates (--project, default cwd). A destination the pack doesn't own, or one edited by hand since install, blocks the install as a conflict; --force overwrites it.

schema: 1
name: xcraft
description: CRM agent pack
plugins:
  - path: plugins/crm
instructions:
  - src: instructions/AGENTS.md
claude:
  skills: [ { src: skills/my-skill } ]

sf pack list / info <name> / status [<name>] / uninstall <name> round out the lifecycle.

sf pack new <name> scaffolds a new, installable pack skeleton to build one from scratch. Already have a project set up the way you like it? sf pack export <name> captures its AGENTS.md and installed plugins into a new pack, ready to install elsewhere or share.

Writing a plugin from scratch rather than pulling one from a pack? sf plugin new <name> scaffolds a working one — see docs/plugins.md for the 5-minute walkthrough. For a declarative plugin with no code — one that just names your project's layers and lets the host synthesize layers/grep/refs grouped by layer — reach for a Tier-1 adapter (sf plugin new <name> --adapter); see docs/adapters.md. Building a Go tool instead of a plugin? The parsers and primitives behind sf itself are importable directly — see docs/sdk.md.

Layout

sofia/
├── embed.go                      # go:embed the sf-context skill (package sofia; used when there's no repo checkout)
├── cmd/                          # Go binary entry points (one per tool)
│   ├── sf/                       # master CLI with all subcommands
│   └── common/<tool>/            # standalone binaries: grep, cc, code, changed, doctor,
│                                  #   composer, packagist, github, vue, worktrees
├── internal/                     # reusable packages
│   ├── calllog/                  # JSONL call log (XDG path) + Counter + Fingerprint
│   ├── cc/                       # `sf cc` — Claude Code session digests
│   ├── cli/                      # Cobra command tree for the master binary (RootCmd)
│   ├── common/changed/           # `sf changed` — classified git diff
│   ├── common/code/              # `sf code` — structural file summary (Go/PHP/TS/Vue)
│   ├── common/composer/          # `sf composer` — PHP package tree overview
│   ├── common/doctor/            # `sf doctor` — installation health (staleness)
│   ├── common/github/            # `sf github` — CI runs, PR digest, branch cleanup
│   ├── common/grep/              # `sf grep` — cross-project search
│   ├── common/gripe/             # `sf gripe` — feedback on silent misses
│   ├── common/hook/              # `sf hook pre` — PreToolUse guard for the Read channel
│   ├── common/initcmd/           # `sf init` — per-project onboarding (AGENTS.md, skill, hook, MCP)
│   ├── common/packagist/         # `sf packagist` — release status + publishing
│   ├── common/refs/              # `sf refs` — symbol def/use finder with enclosing context
│   ├── common/vue/               # `sf vue routes` — vue-router route map
│   ├── common/worktrees/         # `sf worktrees` — cross-project worktree overview
│   ├── envfile/                  # .env load/save/prompt
│   ├── history/                  # `sf history` — reads and aggregates the call log
│   └── launch/                   # `sf claude` — launch Claude Code for a project
├── pkg/                          # public Go SDK (Tier 3, semver-stable) — see docs/sdk.md
│   ├── cliflags/                 # shared flag helpers (--md/--json, dir completion, arg hints)
│   ├── codectx/                  # enclosing-function lookup for PHP/TS/Twig/INI
│   ├── emit/                     # output budget: compact-or-raw (SmallerOf)
│   ├── matcher/                  # line-based search (literal + regex)
│   ├── php/                      # PhpSymbolReader (VKCOM/php-parser AST)
│   ├── strdist/                  # Levenshtein for typo hints (did you mean)
│   ├── tokens/                   # fast heuristic LLM token estimate
│   ├── toon/                     # TOON primitives (Scalar, JoinList)
│   └── walker/                   # parallel tree walker
└── bin/                          # gitignored — build artifacts