@tcoz/codeloop
v8.6.0
Published
AI-first knowledge graph framework for model-authored documentation
Maintainers
Readme
CodeLoop
A convergence loop for coders. The knowledge graph is the interface through which human intent converges to model-authored artifacts.
Installation
From the npm registry (no prior install needed — npx fetches on demand):
npx @tcoz/codeloop init*** DO NOT INSTALL CODELOOP GLOBALLY. It is intended to travel with the project. ***
From this repo (local development or pre-release):
npm install && npm run build && npm linkThen codeloop init works as a command in any project directory. Alternatively, npm run pack produces a .tgz you can install directly into a target project with npm install ./tcoz-codeloop-<version>.tgz.
How to Use
List commands and command-specific options without changing the project:
npx @tcoz/codeloop --help
npx @tcoz/codeloop <command> --helpPrimary commands are init, compile, corpus, viewer, and continuity. codeloop --version prints the installed version. The optional serve adapter is available only for explicitly configured MCP clients. Running codeloop with no command also shows help.
In your project directory, run:
npx @tcoz/codeloop init --role <code-steward|continuity-steward|contributor|continuity>init saves the role in codeloop/role.local.json and compiles one directive file, codeloop/AGENT.md, which the model loads every session. Both files are local to the checkout and git-ignored; init adds the ignore rules. Each role uses its default plugins (git, s3).
Choosing a role per checkout
The role belongs to each checkout, not to the project, so several harnesses can work one project in different roles. To set or switch it:
npx @tcoz/codeloop init --role <role> --force
npx @tcoz/codeloop compile --check| Role | Plugins |
| --- | --- |
| contributor | git |
| code-steward | git |
| continuity | s3 |
| continuity-steward | git, s3 |
init is the only command that sets the role. codeloop compile --role <role> previews another role's directives on stdout and never writes. With no role set, compile and compile --check fail with no role set; run \codeloop init --role --force`, and the session directives halt until the human picks a role. Never commit codeloop/AGENT.mdorcodeloop/role.local.json`; continuity sync never uploads them.
After a framework update:
npx @tcoz/codeloop init --force # or: npx @tcoz/codeloop compileThis recompiles codeloop/AGENT.md for the checkout's role without touching the corpus. codeloop compile --check exits nonzero when no role is set, or AGENT.md is missing, hand-edited, or from an older package.
Upgrading from 7.x: see docs/migrating-to-8.0.0.md.
Root AGENTS.md: CodeLoop never edits it unless you run codeloop agents-pointer, which writes one block between <!-- codeloop:begin --> and <!-- codeloop:end --> pointing at codeloop/AGENT.md, and touches nothing outside those markers (--remove takes it out).
To inspect the corpus in a browser:
npx @tcoz/codeloop viewerThe command starts a read-only viewer on 127.0.0.1 and prints its local URL. Use --cwd <path> to target another project or --port <number> to choose a port.
To test S3 continuity with an existing bucket and AWS credentials:
npx @tcoz/codeloop continuity attach --bucket <bucket> --project <id> --new
npx @tcoz/codeloop continuity syncIn a fresh initialized folder, omit --new to attach and pull the synchronized project. Run npx @tcoz/codeloop continuity --help for status, repair, and asset commands. If sync fails (for example after an interrupted push), codeloop continuity repair diagnoses the state as a dry run; --apply completes safe recoveries, and --apply --overwrite-remote or --apply --overwrite-local replaces one side only when you name the authoritative side. Attachment metadata is machine-local and ignored by Git.
Asset pushes are autonomous: the continuity bot pushes when it judges a capture correct (overwrites included) and then reports the new and overwritten files; pulls still need approval of each preview. Say "be careful about asset pushes" to have the bot preview and ask before every push until you lift it. S3 versioning is the undo; to restore a prior version of a pushed asset with the aws CLI:
aws s3api list-object-versions --bucket <bucket> --prefix <prefix>/<project>/assets/<path>
aws s3api copy-object --bucket <bucket> --key <prefix>/<project>/assets/<path> \
--copy-source "<bucket>/<prefix>/<project>/assets/<path>?versionId=<version-id>"The restore is itself a new version, so it can be undone the same way.
Continuity only: @tcoz/codeloop-continuity is a smaller package that compiles the continuity role into codeloop/AGENT.md and creates the corpus, with the init, compile, and continuity commands (no steward, contributor, MCP adapter, or viewer). It includes corpus share for reading other projects' corpora. Its command is also named codeloop, so install only one of the two packages globally on a machine.
npx @tcoz/codeloop-continuity initAll codeloop/* files are model-owned or framework-controlled.
This is not a setup task. It is an iterative practice. The framework earns its value over multiple sessions — not one. Pass 1 produces a starting point. Each subsequent session grounds inferred facts, resolves HUMAN FILL markers, and catches drift.
Field observation (production use): The effect compounds. Working through complex, multi-step production changes, the process becomes measurably more prescriptive and quality-based — less brute force, more procedural. Results are unusually detailed and precise. The model improves the longer it operates inside the framework. Occasional reminders to self-document are enough; the rest runs autonomously.
Sessions can be shut down and resumed with full confidence. The framework is the bridge across model statelessness — models have no persistent memory between sessions, they are either on or not. The docs are what make resumption exact rather than approximate. When the next session loads the corpus.db, the model is not reconstructing context from scratch; it is reading verified state. The session boundary stops mattering.
Releasing
- Bump the version on dev (
package.json,package-lock.json, CHANGELOG;FRAMEWORK_VERSIONin compiled files comes frompackage.json), then merge to main via PR. - Create a GitHub release
v<version>on main..github/workflows/publish.ymlruns the tests and publishes@tcoz/codeloopand@tcoz/codeloop-continuitywith npm trusted publishing (OIDC); versions already on npm are skipped. - Fallback: run
npm publish --auth-type=webin the repo root and inbuild/continuityafternpm run build:continuity.
Model Requirements
This framework requires an AI model operating in agent mode with sustained context. Contributors run development loops, stewards maintain canonical code-project state, and continuity authors maintain a distilled project projection through a separate continuity runtime.
Context capacity, autonomous file-write capability, terminal access, and sustained reasoning are requirements. Instruction-following-only or non-agentic models will likely produce unreliable results.
Files
| File | Purpose |
| --- | --- |
| codeloop/role.local.json | This checkout's role (code-steward, continuity-steward, contributor, continuity) and permissions mode (strict, trusted, custom); git-ignored, written by init |
| codeloop/AGENT.md | The compiled session directives for that role; git-ignored; generated by init/compile; do not edit |
| codeloop/corpus.db | All corpus records, claims, facts, and sentinels (model-owned) |
Directive source lives in the package under templates/init/: roles/ (one plain file per role), steward/ (blocks shared by both steward roles), plugins/<git|s3>/ (technology blocks per role), permissions/<strict|trusted|custom>/ (the RELEASE gate per role; default strict), core/header.md, and manifest.json. codeloop reference ai-docs prints the framework spec; codeloop reference bootstrap prints the bootstrap guide. Stewarding requires a strong reasoning model; there is no approved-model list.
Useful Prompts
- Start a session (any role): "Load
codeloop/AGENT.mdcompletely and follow it." - Use the corpus: Run
codeloop corpus --help; every steward and contributor corpus operation is available through this CLI. Pass--corpus <path>(or setCODELOOP_CORPUS) to work on a corpus.db outsidecodeloop/, for example a contributor's private corpus;codeloop corpus context --role contributorreturns corpus data without steward directives;--role code-stewardincludescodeloop/AGENT.md(or an in-memory compile when there is none).contextis for agents working under CodeLoop;shareis for readers. - Share a corpus:
npx --no-install codeloop corpus share(or--corpus <path>) prints a read-only knowledge digest with no directives: project state, decisions with rationale, facts, observations, and open claims, each labeled settled, observed, or claimed. Use--out digest.mdto hand it to another bot,--format jsonfor machines, and--budget 0for everything. The header shows the framework version, the corpus's last write, and commits since, so readers can judge staleness. If the budget truncates anything,sharesays so: "corpus share exceeds bytes (8 KB default); run consolidation". Any CodeLoop bot reading a project other than its own usesshare(the directives say so); tell it where, e.g. "read the corpus at ../other-project" or a line in AGENTS.md. - Get project status: "What is the current project status?"
- Sync after changes: "Sync the docs — update of corpus.db reflect what we just built."
- Bootstrap a new project: run
codeloop init --role code-steward --force, then: "Loadcodeloop/AGENT.md, readcodeloop reference ai-docsandcodeloop reference bootstrapin full, then bootstrap the docs for this project." - Reorient after deference drift: "Docs First Principle please. Exercise your option, or don't — your call."
- Deference self-audit: "Review the corpus against the deference directives. Prune or rewrite anything written out of deference rather than derivability."
