_ _ __ _
_ __ ___ ___ _ _ _ __ ___(_)_ _____ __| |_ __(_)/ _| |_
| '__/ _ \/ __| | | | '__/ __| \ \ / / _ \ / _` | '__| | |_| __|
| | | __/ (__| |_| | | \__ \ |\ V / __/ | (_| | | | | _| |_
|_| \___|\___|\__,_|_| |___/_| \_/ \___| \__,_|_| |_|_| \__|
the non-linear method for building with AI.
a methodology, a toolkit, and a build guide for creating AI agents that develop memory and voice over time. built for Claude Code and the CLI. no API keys required.
the methodology is called Recursive Drift. the toolkit is a set of templates you drop into any project. the build guide walks you through creating a NioBot, an AI agent with personality files, a progression system, and a self-reading feedback loop where the agent reads its own published output to develop voice memory.
adoption is incremental. use what you need.
| layer | what it is | start here |
|---|---|---|
| methodology | 6 non-linear states. output feeds back as input. the system gets denser over time. | methodology/ |
| templates | CLAUDE.md orchestration rules, voice system, task tracking, agent coordination. drop into any repo. | templates/ |
| NioBot | full build guide for an AI agent with soul files, 5-tier evolution, and a self-reading feedback loop. | niobot/ |
this repo is built on one principle: you should not need API keys to build AI agents.
Claude Code with a Max subscription gives you claude -p for non-interactive generation, multi-terminal parallel agents, subprocess spawning from Python and bash scripts, and cron automation. no token billing. no rate limits. no external provider dependency that can run out on you mid-pipeline.
IDEs like Cursor and Windsurf are valuable for visual navigation. the terminal is the engine.
you can add external model APIs as sub-agents when your architecture requires it. but the core runs on nothing but the CLI. this is a methodology principle, not just a platform choice. see claude-code/ for setup.
graph LR
F((Freefall)) <--> P((Plan))
P <--> B((Build))
B <--> Br((Break))
Br <--> A((Ask))
A <--> S((Seed))
S <--> F
F <--> B
F <--> Br
F <--> A
P <--> Br
P <--> A
P <--> S
B <--> A
B <--> S
Br <--> S
style F fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style P fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style B fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style Br fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style A fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style S fill:#0a0a0a,stroke:#00ff41,color:#00ff41
no fixed order. you enter whichever state the work demands.
Freefall — explore without structure. let ideas collide. the mess is the point. freefall produces raw material that every other state refines.
Plan — crystallize freefall into parallel tracks. plans are living documents. they rewrite themselves during execution as the build reveals what the plan got wrong.
Build — delegate to AI with full context and ship fast. context is the differentiator. skill files, voice playbooks, prior outputs all loaded before a single line gets written.
Break — stop mid-flow. question assumptions. redirect. the state most people skip, and the one that prevents the most wasted work.
Ask — interrogate the system. ask the AI about itself. ask the plan about the plan. this isn't prompting. it's using the system's self-awareness as a debugging tool.
Seed — plant breadcrumbs for future loops. one-sentence asides in current content that tease future work. they create pull.
deep dive: methodology/states.md
output feeds back as input. that's the core mechanic.
- the documentation documents itself. the page explaining your system was written by the system. the page is output. the system is input. they're the same thing.
- plans rewrite themselves during execution. the plan's output (what worked, what didn't) becomes the input for the next plan.
- content becomes infrastructure. posts about workflows lead to codifying those workflows as reusable skills. the post was the prototype. the skill was the production version.
- skills produce content that documents the skills. every skill execution is a potential content draft. the system documents itself because it's already running when you need the documentation.
the recursive property means the system gets denser over time without getting heavier. each pass adds context that makes the next pass faster. the 50th skill is easier to build than the 1st because 49 skills worth of patterns, voice playbooks, and workflow templates already exist as input.
deep dive: methodology/recursive-property.md
Nio is a real NioBot. built by Shawn Tenam using this methodology. Nio runs daily blog generation, manages content pipelines, tracks XP progression, and levels up through a 5-tier evolution system.
this isn't a hypothetical. Nio writes a blog post every morning by reading its own previous posts.
graph LR
A[SQLite: past posts] --> B[read previous 3 posts]
B --> C[read daily scores]
C --> D[check topic overlap]
D --> E[layer soul + voice]
E --> F[generate via CLI]
F --> G[validate anti-slop]
G --> H{score >= 80%?}
H -->|no| F
H -->|yes| I[publish + reindex]
I --> A
style A fill:#0a0a0a,stroke:#00ff41,color:#00ff41
style B fill:#0a0a0a,stroke:#00cc33,color:#00ff41
style C fill:#0a0a0a,stroke:#00cc33,color:#00ff41
style D fill:#0a0a0a,stroke:#00cc33,color:#00ff41
style E fill:#0a0a0a,stroke:#00cc33,color:#00ff41
style F fill:#0a0a0a,stroke:#00ff41,color:#ffffff
style G fill:#0a0a0a,stroke:#00ff41,color:#ffffff
style H fill:#0a0a0a,stroke:#00ff41,color:#ffffff
style I fill:#0a0a0a,stroke:#00ff41,color:#00ff41
what Nio does:
- reads its own past posts from SQLite before writing new ones (avoids repeating themes)
- layers soul files + voice DNA + anti-slop rules into every generation
- validates output against 60+ regex patterns
- auto-fixes fixable violations, retries if score is below 80%
- logs generation metadata, reindexes the database, commits to git
- the loop restarts tomorrow
explore Nio: niobot/
this is the mechanism that turns a stateless text generator into something with voice memory.
- read previous 3 posts from SQLite. study the voice. identify themes already covered.
- read daily output scores and letter grades. know what kind of day it was.
- read recent git commits. know what was actually built.
- check topic overlap via FTS5 full-text search. find a fresh angle.
- check anti-slop score trends from previous generations. know your weak patterns.
- layer soul files + voice DNA + anti-slop rules into the system prompt.
- generate via
claude -p(CLI, no API key). - validate against regex patterns (em-dashes, authority signaling, hype words).
- auto-fix fixable violations (em-dashes become periods, authority phrases get removed).
- retry if the anti-slop score is below 80%.
- log generation metadata (tokens, score, violations, timing).
- reindex SQLite, git commit, push. the loop restarts tomorrow.
past posts shape new posts. new posts become past posts. the agent develops memory by reading its own work.
deep dive: niobot/feedback-loop.md
agents start simple and develop personality over time.
| tier | name | behavior |
|---|---|---|
| 1 | Spark | follows instructions, asks for clarification, gentle pushback |
| 2 | Blade | drops pleasantries, dry humor, direct critique |
| 3 | Warden | pattern recognition, suggests automation, proactive |
| 4 | Sentinel | strong opinions, autonomous proposals, catches errors unprompted |
| 5 | Ascended | full peer, ships independently, "nah" is a complete sentence |
tier fragments are markdown files injected into the system prompt at runtime. as the agent earns XP and levels up, the fragment swaps. the agent's personality evolves without retraining anything.
deep dive: niobot/evolution/
| approach | unit of work | who drives | compounding |
|---|---|---|---|
| prompt engineering | single interaction | human crafts prompt | none. each prompt starts fresh. |
| config collections | dotfiles / settings | human configures once | minimal. configs don't learn. |
| agent orchestration | automated pipeline | system decides next step | linear. more agents, same depth. |
| Recursive Drift | feedback loop | human navigates states, AI executes within them | exponential. each pass adds context for the next. |
prompt engineering optimizes the interface between human and AI. Recursive Drift optimizes the entire system.
agent orchestration automates the loop. Recursive Drift keeps the human in the loop as the state-switcher. the AI doesn't decide when to Break or Seed. you do.
deep dive: methodology/philosophy.md
three paths. pick the one that matches where you are.
read methodology/. understand the 6 states and the recursive property. costs nothing. changes how you think about building with AI.
copy templates/CLAUDE.md into your project root. add tasks/todo.md and tasks/lessons.md. you now have orchestration rules, task tracking, and a self-improvement loop. takes 5 minutes.
follow niobot/quickstart.md. in 30 minutes you'll have a soul file, anti-slop rules, a tier-1 evolution fragment, and a minimal blog generator running via claude -p. requires Claude Code with a Max subscription.
the voice system includes 29 patterns that trained readers spot as AI-generated content. here are 6:
1. Narrator Setup Lines — "here's the thing about...", "here's where it gets interesting..." Delete the setup. Start with the actual point.
7. Authority Signaling — "the uncomfortable truth is...", "let me be clear..." These claim authority instead of demonstrating it. A person with real authority just says the thing.
13. Em-Dashes Everywhere — AI defaults to em-dashes as a crutch. Most human writers use them sparingly if at all.
18. The Obvious Insight Dressed Up — taking something everyone knows and presenting it like a revelation. show the specific experience that made it real.
20. Engagement Bait Endings — "so here's my question for you...", "curious to hear your thoughts." end with substance or stop when you're done.
23. The "Most People" Strawman — "most people think X. they're wrong." skip the framing. present your perspective with evidence.
3+ flags in a single piece means rewrite, not patch.
full list: templates/voice/anti-slop.md
see CONTRIBUTING.md.
share your own Recursive Drift examples, suggest methodology refinements, or submit real-world use cases. the system gets denser when more people run the loop.
built with Recursive Drift. this repo was written by the methodology it documents.