[P3] ~3,200 tokens always-on overhead — compress base config

[sepehrn0107]

Problem

Every session loads ~12,858 bytes (~3,200 tokens) of toolbox instructions via CLAUDE.global.md, regardless of whether toolbox features are needed. Biggest contributors:

• session-start.md: 3,159 bytes — complex branching logic that runs once
• skill-routing.md: 2,769 bytes — a lookup table
• lifecycle-skills.md: 2,255 bytes — a path map (redundant with routing table)

Proposed Fix

• Merge lifecycle-skills into skill-routing (eliminate duplicate references)
• Move session-start logic into the hook script itself
• Investigate compressing the routing table format

[sepehrn0107]

---

issue: "3.4 Always-on token overhead"
priority: P3
type: enhancement
date: 2026-04-07

Implementation Plan: Compress Base Config Token Overhead

Problem Summary

Every session loads ~12,957 bytes (~3,242 tokens) via CLAUDE.global.md. Three files dominate:

File	Bytes	Est. tokens
session-start.md	3,159	~790
skill-routing.md	2,743	~686
lifecycle-skills.md	1,576	~394
codex-integration.md	1,286	~322
others + header	~3,994	~849
Total	12,957	~3,242

Key redundancies:

1. session-start.md — WORKSPACE_MODE branching logic (~1,400 B) duplicates what the hook already outputs
2. lifecycle-skills.md — 27-line path map entirely superseded by the path-inference rule already in skill-routing.md
3. skill-routing.md — HTML comment block and verbose trigger phrases can be compressed

Target: ~830 tokens saved (~26% reduction), zero behavior change.

Files to Change

Template file	Action
templates/sections/session-start.md	Rewrite with condensed WORKSPACE_MODE handling
templates/sections/lifecycle-skills.md	Delete — content merged into skill-routing
templates/sections/skill-routing.md	Add path inference rule; compress tables; remove HTML comment
templates/CLAUDE.global.md	Remove @…/lifecycle-skills.md include line
templates/sections/vault-paths.md	Remove one redundant trailing sentence
templates/sections/codex-integration.md	Collapse numbered lists into phase table

Step-by-Step Changes

Step 1 — Merge lifecycle-skills into skill-routing (~420 tokens saved)

lifecycle-skills.md only tells Claude the path for each command. The path is always {{TOOLBOX_PATH}}/skills/<slug>.md. The closing sentence in skill-routing.md already states this pattern.

1. Add one sentence to the end of skill-routing.md:

   Read the skill file from {{TOOLBOX_PATH}}/skills/<skill>.md before following it. Skills not in the table follow the same path pattern.

2. Delete templates/sections/lifecycle-skills.md
3. Remove the @{{CLAUDE_PATH}}/toolbox-sections/lifecycle-skills.md line from templates/CLAUDE.global.md

Step 2 — Compress session-start.md (~200 tokens saved)

Replace the verbose WORKSPACE_MODE branching prose with:

## Session Start (automatic)

> **Sub-agent check:** If `WORKSPACE_MODE:` is absent from context, skip this block.

On session start:
1. Check for project memory at `{{VAULT_PATH}}/02-projects/<name>/memory/MEMORY.md`.
   Read first 3 lines of: project_context.md, stack.md, architecture.md, progress.md,
   lessons.md (summaries only; load full files on-demand).
2. Read first 5 lines of `{{VAULT_PATH}}/05-areas/claude-memory/MEMORY.md` (global index).
3. Note if `.claude/index/README.md` exists.
4. Invoke `codex:setup`; store as `CODEX_AVAILABLE`. Do not re-check this session.
5. Output: `Toolbox: active | Skills: ready | Standards: auto-load on first edit`
   Append ` | Project: <name> | Stack: <stack>` if a project is loaded.

**WORKSPACE_MODE handling:**
- `ACTIVE=<name>`: store SESSION_ID → session file, load that project's memory summaries.
- `CHOOSE`: treat user's first message as project choice. Write to session file + active-project.md.
  If not valid, re-show list and wait.

Step 3 — Compress skill-routing.md (~140 tokens saved)

1. Remove the HTML comment block (plugin cache paths — no runtime value for Claude)
2. Condense internal auto-route trigger phrases (e.g. "Multiple git commands" → "Multiple git ops")
3. Collapse the two upgrade rows into one

Step 4 — Minor trims (~70 tokens saved)

File	Change	Savings
vault-paths.md	Remove redundant "These paths are rendered at install time..." sentence	~30 tokens
codex-integration.md	Collapse two identical 4-step lists into a single phase table	~40 tokens

Token Savings Summary

Change	Tokens saved
Step 1: Eliminate lifecycle-skills.md	~420
Step 2: Compress session-start.md	~200
Step 3: Compress skill-routing.md	~140
Step 4: Minor trims	~70
Total	~830 tokens

Baseline ~3,242 → target ~2,410 (~26% reduction).

Validation Steps

# Byte count check
wc -c templates/sections/*.md templates/CLAUDE.global.md
# Target: total ≤ 10,500 B (down from 12,957 B)

# Word count proxy
wc -w ~/.claude/toolbox-sections/*.md ~/.claude/CLAUDE.global.md
# Target: ≤ 2,600 total words

Functional checks after /upgrade:

1. Status line appears correctly in new session
2. WORKSPACE_MODE:ACTIVE loads project memory summaries
3. WORKSPACE_MODE:CHOOSE presents list; first-message selection works
4. Skill routing still triggers correctly (test 4+ routes)
5. Lifecycle path resolution: /git-push resolves via path-inference rule (not deleted lifecycle-skills list)

Parallelism Guide

Group	Tasks	Dependency
1 (parallel)	Edit session-start.md + Edit skill-routing.md + Edit vault-paths.md + Edit codex-integration.md	None
2 (after 1B)	Delete lifecycle-skills.md + Edit CLAUDE.global.md	Confirm 1B absorbed lifecycle content
3 (after 1+2)	Run byte count + /upgrade smoke-test	Both groups complete