Every time you ask an AI coding assistant a question, it often starts from scratch.
"Where is authentication implemented?"
"Who calls
UserService?""How does this API flow work?"
Instead of remembering your architecture, the model crawls dozens of files again. That means more tokens, higher cost, slower responses, and more opportunities for hallucinations.
After experimenting with AI-assisted development, I found that the biggest optimization isn't choosing a different model --- it's changing what you send to the model.
This article covers a layered workflow for making AI agents dramatically more efficient using OKF, persistent project memory, on-demand skills, and token compression.
Why token optimization matters
LLMs don't read code the way humans do. Everything becomes tokens processed through transformer layers.
Every unnecessary file, log, or repeated explanation increases:
- 💰 Cost (for paid APIs)
- ⏱️ Latency
- 🧠 Context window usage
- ❌ Risk of losing important information
The goal isn't to provide less context. It's to provide better structured context.
Layer 1: Replace raw code with structured knowledge
The biggest improvement comes from avoiding repeated file reads entirely.
Instead of feeding an LLM your repository every session, generate a knowledge bundle once and let the agent query that instead. This is the core idea behind OKF (Optimised Knowledge Format). It extracts your project's architecture --- classes, functions, APIs, relationships, and modules --- into structured Markdown that both humans and AI agents can navigate efficiently.
Traditional workflow:
Question
│
▼
Read 40 files
│
▼
Understand architecture
│
▼
Answer
OKF workflow:
Question
│
▼
Read knowledge bundle
│
▼
Jump directly to implementation
│
▼
Answer
The difference is simple:
| Without OKF | With OKF |
|---|---|
| Re-reads source files | Queries structured concepts |
| Large token usage | Small, focused context |
| Slower reasoning | Faster navigation |
| Architecture rediscovered every session | Architecture indexed once |
Meet OKF Generator
The easiest way to generate these knowledge bundles is with OKF Generator, an open-source CLI that scans a repository and produces an OKF bundle using static analysis --- no LLM required. It supports incremental updates, agent integrations, and even a zero-LLM workflow where you can generate and query bundles entirely offline.
GitHub: https://github.com/UmairBaig8/okf-generator
Getting started:
pip install okf-generator
# Generate your first bundle
okf generate
# Update it after new changes
okf update
# Install integrations for AI agents
okf install all
Once generated, point your agent to the bundle instead of your entire repository. The bundle is plain Markdown, version-controllable, and designed to live alongside your source code.
Not Just Claude: OKF Works With Any Agent
OKF goes beyond token optimization. When onboarding developers to a large codebase, you can give any LLM the generated okf_bundle and ask it to explain the project, identify key components and their relationships, and generate a Mermaid diagram.
This provides a quick, high-level overview of the codebase and can significantly reduce onboarding time.
For this example, using a local LLM(gpt-oss20b), I asked it to analyze C:\Code\uigen\okf_bundle and generate a Mermaid diagram with an explanation of the project's key components and how they interact.
All the components, explanations, and web flow were generated in less than 2 minutes.
Layer 2: Give your project a memory (CLAUDE.md)
Most developers repeatedly explain the same things:
- How to run the project
- Coding conventions
- Folder structure
- Architectural decisions
That information belongs in CLAUDE.md, a persistent Markdown file automatically loaded at the beginning of every session. It eliminates repeated briefings and keeps foundational project knowledge available without bloating every prompt.
A good CLAUDE.md contains:
# Project Rules
- Use pnpm instead of npm
This project has an OKF knowledge bundle at ./okf_bundle/.
- Use `okf lookup <Name>` for full concept context.
- Use `okf lookup --type <Type>` to filter by type.
- Read `SUMMARY.md` for the full knowledge map.
Instead of repeating these instructions across conversations, they're loaded automatically.
File locations:
# Project-level
./CLAUDE.md
./.claude/CLAUDE.md
# User-level
~/.claude/CLAUDE.md
Layer 3: Load knowledge only when needed (Skills)
Not everything deserves permanent context.
Deployment guides, review checklists, compliance docs, and long API references are better stored as Skills. Skills are reusable SKILL.md files that stay out of the main context until the task requires them, keeping the default prompt lean while still making detailed workflows instantly available.
Good examples include:
/deploy/release/review/database-migration
Your default context stays small, but expertise is always one command away.
File locations:
.claude/skills/<name>/SKILL.md
# or
~/.claude/skills/<name>/SKILL.md
Layer 4: Automate consistency with Hooks
Hooks aren't about saving tokens directly. They're about preventing expensive mistakes.
Examples:
- Auto-format after every edit
- Block dangerous shell commands
- Notify you when an agent finishes
- Run linting automatically
Since hooks fire at predefined lifecycle events, they remove repetitive instructions from your prompts entirely.
File locations:
.claude/settings.json
# or
~/.claude/settings.json
Keep your knowledge bundle up to date
A stale architecture is almost as bad as no architecture.
You can regenerate your OKF bundle automatically using GitHub Actions whenever someone pushes to main or opens a pull request. The workflow keeps your AI context synchronized with your codebase and can even generate impact summaries for reviews.
name: OKF Bundle
on:
push:
branches: [main]
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install okf-generator
- run: okf generate . okf_bundle
Now your AI always understands the latest architecture.
Reduce output tokens too
Optimizing input is only half the story.
Two complementary tools solve different problems:
| Tool | Optimizes |
|---|---|
| OKF | What the model reads |
| caveman | What the model writes |
| rtk | Terminal and tool output |
If your context is filled with git diff, build logs, or test output, rtk trims that before it ever reaches the model. If your assistant tends to produce verbose explanations, caveman keeps responses concise. Together they reduce both sides of the token equation.
The complete token-efficient workflow
Each layer removes a different source of waste:
| Layer | What it eliminates |
|---|---|
| OKF | Re-reading source files |
| CLAUDE.md | Repeating project briefings |
| Skills | Loading reference docs unnecessarily |
| Hooks | Repeating operational instructions |
| caveman / rtk | Verbose output and noisy logs |
Final thoughts
The future of AI development isn't about endlessly increasing context windows. It's about making context intentional.
A well-structured repository gives AI assistants the same advantage it gives human developers: they spend less time searching and more time solving problems.
If you're already using Claude Code, Cursor, Copilot, or another AI coding assistant, try generating an OKF bundle for your next project. You'll probably notice the difference long before you notice the token savings.
Resources
If you've been experimenting with token optimization or AI developer workflows, I'd love to hear what's working for you in the comments.
Top comments (0)