npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tcoz/codeloop

v8.6.0

Published

AI-first knowledge graph framework for model-authored documentation

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 link

Then 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> --help

Primary 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 compile

This 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 viewer

The 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 sync

In 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 init

All 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

  1. Bump the version on dev (package.json, package-lock.json, CHANGELOG; FRAMEWORK_VERSION in compiled files comes from package.json), then merge to main via PR.
  2. Create a GitHub release v<version> on main. .github/workflows/publish.yml runs the tests and publishes @tcoz/codeloop and @tcoz/codeloop-continuity with npm trusted publishing (OIDC); versions already on npm are skipped.
  3. Fallback: run npm publish --auth-type=web in the repo root and in build/continuity after npm 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.md completely 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 set CODELOOP_CORPUS) to work on a corpus.db outside codeloop/, for example a contributor's private corpus; codeloop corpus context --role contributor returns corpus data without steward directives; --role code-steward includes codeloop/AGENT.md (or an in-memory compile when there is none). context is for agents working under CodeLoop; share is 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.md to hand it to another bot, --format json for machines, and --budget 0 for 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, share says so: "corpus share exceeds bytes (8 KB default); run consolidation". Any CodeLoop bot reading a project other than its own uses share (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: "Load codeloop/AGENT.md, read codeloop reference ai-docs and codeloop reference bootstrap in 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."