Skip to content

README.md

Latest commit

 

History

History
56 lines (38 loc) · 2.56 KB

README.md

File metadata and controls

56 lines (38 loc) · 2.56 KB
Raw

codeview

A mostly headless CLI (built with Bun + OpenTUI) that keeps a registry of reference codebases and clones them into a project's resources/ folder so coding agents can read them for patterns, templates, and examples.

Install

Codeview requires Bun 1.2 or newer. Run it without installing:

bunx @oddofrancesco/codeview --help

Or install the command globally:

bun add --global @oddofrancesco/codeview

Usage

codeview add <git-url> [--name <name>] [--desc "what it does"]
codeview describe <name> "<description>"
codeview remove <name>
codeview list
codeview setup                 # interactive fuzzy picker
codeview setup <name...>       # headless: specific repos
codeview setup --all [--force] # headless: everything
codeview update                # refresh installed repos from their configured sources

setup stages repos before publishing them into ./resources/ (without .git), adds resources/ to .gitignore, and adds a section to both AGENTS.md and CLAUDE.md (creating them if missing) telling agents to read those folders. Codeview records the directories it owns in resources/.codeview-manifest.json; it refuses to replace an existing directory that is not in that manifest.

Repeated setup calls are incremental. Previously installed repos remain in the manifest and agent documentation, while the requested repos are replaced as one project transaction.

  • Registry: ~/.config/codeview/repos.json
  • Global cache: ~/.cache/codeview — repos fetched < 1 week ago are reused without network
  • Materialization: Codeview attempts copy-on-write file clones first and transparently falls back to ordinary copies when the source and project are on different devices or the filesystem does not support cloning

Acknowledgements

Codeview's filtered copy-on-write materializer is adapted from Rift's APFS and Linux reflink strategies. Rift established the tree-walk, hard-link preservation, per-file clone, and unsupported-filesystem fallback design; Codeview reimplements that design in TypeScript using Bun's filesystem APIs while retaining Codeview's own transactional publishing model. Rift declares its source under the MIT license.

Development

bun install
bun run test
bun run typecheck

Test discovery is restricted to the first-party test/ directory, so reference codebases under resources/ are never included.

License

Codeview is available under the Apache License 2.0.