locode: Instructions file for Claude Code

Locode — Claude Code Instructions

Project

TypeScript CLI that routes tasks between Ollama (local LLM) and Claude based on task complexity. Goal: measurable token savings.

Essential Commands

npm install          # install deps
npm test             # run vitest (must pass before any commit)
npm run build        # tsc compile → dist/
npm run dev          # ts-node src/index.ts (no build needed)
./dist/src/index.js  # run compiled CLI (after build)

Dev Workflow

All changes go through a branch + PR:

git checkout -b fix/<issue>   # or feat/<feature>
# make changes, npm test, npm run build
git push -u origin <branch>
gh pr create --fill

Never commit directly to main. PRs require passing tests (prepublishOnly enforces this on publish).

Release Process

Releases are tag-driven. CI never commits to main. The publish workflow fires on any v* tag push.

# 1. Create a release branch from clean main
git checkout main && git pull
git checkout -b release/vX.Y.Z

# 2. Bump version in package.json only (no commit, no tag)
npm run release:patch   # or release:minor / release:major

# 3. Commit the version bump and open a PR
git add package.json package-lock.json
git commit -S -m "chore: release vX.Y.Z"
git push -u origin release/vX.Y.Z
gh pr create --fill

# 4. After PR is merged, push a signed tag from local main
git checkout main && git pull
VERSION="v$(node -p "require('./package.json').version")"
git tag -s "$VERSION" -m "Release $VERSION"
git push origin "$VERSION"

Key rules:

• Never run npm version without --no-git-tag-version in the bump step — the tag must be created after merge, not before
• Never push the tag before the PR is merged — the tag should point to the commit on main
• The publish workflow (.github/workflows/publish.yml) handles build, test, npm publish, and GitHub Release creation automatically

Non-negotiable Rules

1. TDD always — write failing test, run it, implement, confirm pass, commit
2. All tests must pass before committing — run npm test
3. Build must succeed — run npm run build and fix TypeScript errors
4. No shell strings — use execFileSync(cmd, args[]) not execSync('cmd args'). If a shell pipe is genuinely required (e.g., curl | sh), keep the shell form but add an inline comment explaining why
5. Shell allow-list — src/tools/shell.ts uses ALLOWED_COMMANDS Set; never switch to deny-list
6. Config-driven models — never hardcode 'qwen3:8b' or 'claude-sonnet-4-6'; use config.local_llm.model and config.claude.model
7. No dead config — if you add a field to src/config/schema.ts, wire it up somewhere
8. Never commit directly to main — always create a branch (git checkout -b feat/<name> or fix/<name>), make changes there, then open a PR with gh pr create
9. schema.ts is the single source of truth for defaults — locode.yaml and setup.ts CONFIG_TEMPLATE must agree with the Zod defaults in src/config/schema.ts. When changing a default, update the schema first, then sync the others
10. Path comparisons need a trailing separator — never use path.startsWith(base) for directory containment checks; use path === base || path.startsWith(base + path.sep) to prevent sibling-directory traversal (e.g., /tmp/repo-evil matching /tmp/repo)
11. No regex backtracking hazards — CodeQL runs on every PR. Avoid alternation patterns like (?:A|B)* where A and B can match the same input. Prefer simple line-based scans over complex multi-line regex when parsing config/YAML