@ include resolution for accurate token counting (re: #4)

[Nubaeon]

Following up on @larachan-dev's question about @ import mechanics from #4.

How Claude Code resolves @ includes

Based on our testing (not official Anthropic docs — behavior observed across 100+ sessions):

Syntax: @path/to/file.md on its own line in CLAUDE.md

Resolution:

• @~/.claude/empirica-system-prompt.md → resolves ~ to home dir, reads the file, injects full content
• Relative paths: @./rules/custom.md → relative to the CLAUDE.md location
• Absolute paths work

What we've confirmed:

• Single-level includes work reliably (A includes B)
• The included content appears in the conversation context as if it were inline
• Claude Code's statusline stdin shows the full cache_read_input_tokens which includes all resolved includes

What we haven't tested:

• Nested includes (A → B → C) — we don't use them
• Circular reference behavior — unknown
• Whether includes work in skills/hooks (we only use them in CLAUDE.md)

Why it matters for token counting:

Our CLAUDE.md is 16 bytes:

@~/.claude/empirica-system-prompt.md

But the included file is 1,191 tokens (lean core) or 6,292 tokens (full prompt). The organizer's token counter sees 16 bytes (~4 tokens) instead of the actual loaded content.

Implementation suggestion:

In the tokenizer, when processing CLAUDE.md content:

1. Scan for lines matching ^@(.+)$
2. Resolve the path (handle ~, relative)
3. Read the target file
4. Count tokens on the resolved content instead of the include directive

This would be ~15 lines of code and would fix the most common underestimation case.

[ithiria894]

Sorry for the late reply — been heads-down fixing bugs and issues from other users the past few days.

Good news: this is already implemented in CCO! The context budget calculator expands @ imports recursively (up to 5 levels deep), resolves ~ home paths and relative paths, and counts tokens on the fully expanded content — not the raw directive.

You can verify by running npx @mcpware/claude-code-organizer@latest and checking the context budget panel — your CLAUDE.md should show ~1.2K–6.3K tokens (the actual included content), not 4 tokens.

Really glad you raised this though — it's exactly the kind of accuracy issue that matters for config planning. If you're seeing different behavior on your end, let me know the version and I'll investigate.