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

@q3-codeforge/codeforge-cli

v1.0.0-beta.1

Published

AI-driven repository bootstrap and engineering standardization CLI

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

q3-codeforgeq3-codeforge

Keywords

aiclideveloper-toolsrepositorybootstrapautomationcodeforge

Readme

CodeForge

Version Platform Go

codeforge is a CLI that prepares repositories and multi-repo workspaces for AI-assisted development. It scans codebases, generates AI instruction files, registers shared context, creates feature prompts, runs Codex or Claude workflows, and records token usage where available.

Current Release Notes

| Item | Value | | --- | --- | | Current CLI release target | 0.1.77 | | Latest previous packaged CLI | 0.1.76 | | Go version | 1.24.2 | | Target platform | Windows amd64 |

If codeforge version prints 0.1.0-dev, the binary was built locally with go build. Release packages must be built with scripts/build-release.ps1 so the version is stamped into the executable.

Why CodeForge Exists

Without CodeForge, AI tools guess your folder structure, naming conventions, testing style, and delivery process. CodeForge creates the working files that tell Codex or Claude how your repository works before implementation starts.

With CodeForge, AI tools can read generated files such as AGENTS.md, CODEX.md, CLAUDE.md, ai-context/, prompts, feature context, and workspace handoffs before making changes.

How It Works

  1. Scan - CodeForge inspects your repo and detects stack, folder structure, tests, conventions, and feature areas.
  2. Generate - It creates instruction files and prompt files for Codex or Claude.
  3. Share Context - In workspace mode, it registers FRS, database schemas, API specs, architecture notes, and UI references.
  4. Design Database - If enabled, it generates a fresh workspace database design from shared FRS context.
  5. Deliver Features - It creates feature-scoped project prompts and can run AI workflows across repos.
  6. Track Usage - It captures token/cost metadata when provider output includes it, and estimates usage when needed.

codeforge supports:

  • Single repo mode - Set up one repository.
  • Multi-repo workspace mode - Coordinate FRS, backend, frontend, shared, legacy, and full-stack repos.

Key Terms

| Term | Meaning | | --- | --- | | Platform | The AI tool used by the repo or workspace, usually codex or claude. | | FRS | Functional Requirements Specification. .docx, .md, and .txt files can be used as requirements context. | | Graphify | Optional Python tool that produces a codebase graph summary. | | Enrich | AI step that replaces generated TODO placeholders with repo-specific detail. | | Role | Repo responsibility in a workspace: frs, backend, frontend, full-stack, legacy, or shared. | | Context | Shared information registered in a workspace, such as FRS, DB schema, API spec, architecture, or UI reference. | | Feature | A delivery unit tracked by name, stage, dependencies, attached context, usage, and completion state. | | Handoff | Artifact passed from one stage to another, such as FRS to backend or backend to frontend. | | Projection | Placing the right prompts and knowledge files into each repo for the active feature. | | Usage | Token and cost metadata captured from AI runs or estimated when exact metadata is unavailable. |

Install

Prerequisites

| Requirement | Why | | --- | --- | | Git | Repository detection and normal development workflow. | | Go 1.24.2 | Required for CLI development. | | Python 3 | Required only for optional Graphify discovery. | | Codex CLI or Claude Code CLI | Required for enrichment, database design, and workspace AI execution. | | Windows 10+ | Current packaged target. |

Optional Graphify install:

py -3 -m pip install graphifyy==0.4.1

Install From Package

From codeforge/:

powershell -ExecutionPolicy Bypass -File .\install.ps1
codeforge version

The installer uses the latest codeforge_<version>_windows_amd64.zip in codeforge/package/, installs the binary to %LOCALAPPDATA%\CodeForge\bin, and adds that folder to user PATH if needed.

Uninstall

codeforge uninstall
codeforge uninstall --dry-run

Single Repo Quick Start

codeforge validate env
codeforge setup --platform claude
codeforge status

Use --platform codex if the repo should target Codex instead of Claude.

Optional improvements:

codeforge setup --platform claude --with-graphify
codeforge maintain enrich --platform claude
codeforge setup --platform claude --skills frs-analysis,dotnet-blazor-n-tier,code-review

Workspace Quick Start

Use this when delivery spans multiple repos, for example FRS, backend API, and frontend UI.

1. Initialize Workspace

codeforge workspace init --name visitor-delivery

This creates codeforge-workspace.json.

2. Register Repos

codeforge workspace repo add --name visitor-frs --path visitor-frs --role frs --platform claude
codeforge workspace repo add --name visitor-api --path visitor-api --role backend --platform claude
codeforge workspace repo add --name visitor-web --path visitor-web --role frontend --platform claude

3. Register Shared Context

codeforge workspace context add --id registration-frs --type frs --path visitor-frs/requirements/visitor-registration.docx
codeforge workspace context add --id registration-screens --type ui-reference --path visitor-frs/features/visitor-registration/screens
codeforge workspace context add --id visitor-db --type db-schema --path visitor-api/docs/schema.sql

Supported context types:

  • frs
  • legacy
  • db-schema
  • db-live
  • api-spec
  • architecture
  • ui-reference

4. Generate Workspace Database Design

Run this when the workspace needs a fresh database design from FRS before backend/frontend implementation:

codeforge workspace database design --force --yes --ci

The command:

  • Requires at least one shared FRS context.
  • Invokes the configured AI CLI.
  • Writes database design artifacts.
  • Registers the generated schema context, usually workspace-database-schema.
  • Does not attach the generated schema to a feature automatically.

Run a preview first when needed:

codeforge workspace database design --dry-run

5. Create And Select A Feature

codeforge workspace feature add --name visitor-registration
codeforge workspace feature select --name visitor-registration

Features can have dependencies and parent relationships. A feature should not run its pipeline until required dependencies are complete.

6. Attach Context To Repos

codeforge workspace attach --repo visitor-api --context registration-frs --context workspace-database-schema
codeforge workspace attach --repo visitor-web --context registration-frs --context registration-screens

Use context IDs directly. Do not hand-edit old shared: or feature: prefixes into the manifest. Current CLI versions migrate old references where possible.

7. Validate, Project, And Run

codeforge workspace validate --ci
codeforge workspace plan
codeforge workspace project --feature-name visitor-registration --ci
codeforge workspace run --feature-name visitor-registration

workspace project generates feature prompts and context files inside participating repos. workspace run invokes Codex or Claude for the selected feature.

8. Handoff Between Stages

codeforge workspace handoff --from frs --to backend
codeforge workspace handoff --from backend --to frontend

Each handoff creates a feature-scoped artifact so the next stage can read decisions, APIs, contracts, and implementation notes from the previous stage.

9. Complete The Feature

codeforge workspace feature complete --name visitor-registration

Complete features can unblock dependent features.

Complete User Flow

Use this plain English explanation with users:

  1. Install the CodeForge CLI.
  2. Confirm codeforge version works.
  3. Open the repo or workspace.
  4. For a single repo, run setup for Codex or Claude.
  5. For a workspace, initialize the workspace.
  6. Add the participating repos.
  7. Add the FRS as shared context.
  8. Add optional UI reference, API spec, architecture, or database context.
  9. Run Workspace Database Design if a new database schema is needed.
  10. Create or select the feature.
  11. Attach the required context to the repos.
  12. Validate the workspace.
  13. Generate project prompts.
  14. Run the AI pipeline or open the prompts manually.
  15. Review usage and cost.
  16. Complete the feature.

What Gets Generated

Single repo setup can generate:

your-repo/
|-- AGENTS.md
|-- CODEX.md / CLAUDE.md
|-- ai-context/
|   |-- rules/
|   |-- knowledge/
|   `-- skills/
|-- prompts/
|   `-- project/
|-- features/
`-- graphify-out/

Workspace commands can also generate:

.codeforge/
|-- workspace-usage.json
features/
|-- <feature>/
|   |-- prompts/
|   |-- handoffs/
|   `-- context/

The exact files depend on workspace roles, active feature, attached context, and selected workflow stage.

Usage And Cost

codeforge records AI usage metadata when the AI CLI returns it. For workspace runs, usage is saved in:

.codeforge/workspace-usage.json

Usage can include:

  • input tokens
  • output tokens
  • total tokens
  • model
  • cost
  • source, such as actual or estimated

Claude users can also run /cost inside Claude Code to inspect the current session cost.

Commands

Everyday Commands

| Command | What It Does | | --- | --- | | codeforge tui | Launch the interactive terminal UI. | | codeforge validate env | Check required environment setup. | | codeforge setup --platform <codex\|claude> | Generate AI working files. | | codeforge status | Show current setup state. | | codeforge maintain enrich --platform <codex\|claude> | Use AI to fill TODO sections. | | codeforge prompts generate --type <type> --name <name> | Create a delivery prompt. | | codeforge workspace validate --ci | Validate workspace manifest and references. | | codeforge workspace database design --force --yes --ci | Generate database design from shared FRS. | | codeforge workspace project --feature-name <feature> --ci | Generate feature project prompts/artifacts. | | codeforge workspace run --feature-name <feature> | Execute AI prompts across workspace repos. | | codeforge workspace feature complete --name <feature> | Mark a feature complete. |

Setup Options

| Option | What It Does | | --- | --- | | --platform codex\|claude | Select the AI platform. | | --with-graphify | Also run Graphify. | | --enrich | Use AI to replace generated TODO placeholders. | | --force | Overwrite existing generated files after backup. | | --dry-run | Show what would happen without writing. | | --skills auto\|none\|ids | Generate AI Skills / Capability Packs. |

Claude And Codex Notes

  • Claude Code must be installed and authenticated before AI execution commands can run.
  • On Windows, current CLI versions prefer claude.cmd or claude.exe to avoid PowerShell execution policy failures from claude.ps1.
  • Claude non-interactive runs use print mode and accept edit permissions for workspace automation.
  • If Claude or Codex reports a quota/usage limit, the CodeForge command fails even when the workspace manifest is valid. Wait for the provider reset or use a different authenticated account.

Troubleshooting

| Problem | Solution | | --- | --- | | codeforge command not found | Re-run install.ps1 and open a new terminal so PATH takes effect. | | codeforge version shows 0.1.0-dev | Build a release with scripts/build-release.ps1; plain go build creates a dev binary. | | codeforge validate env fails on Git | Install Git and make sure it is on PATH. | | codeforge validate env fails on Python | Install Python 3 if Graphify is required. | | Generated files have TODOs | Run codeforge maintain enrich --platform <codex\|claude>. | | --with-graphify fails | Install Graphify with py -3 -m pip install graphifyy==0.4.1. | | Enrichment/database/workspace run fails | Confirm Codex or Claude is installed, authenticated, and not rate-limited. | | Workspace validation fails on context IDs | Use the latest CLI and avoid hand-editing shared: or feature: prefixes into the manifest. | | Database design fails | Confirm FRS context exists, fresh database design is enabled, AI CLI is authenticated, and provider quota is available. | | Project prompts fail for a feature | Run codeforge workspace validate --ci, then check feature dependencies and attached context. | | AI does not follow repo rules | Open AGENTS.md; if it has TODO sections, run codeforge maintain enrich. |

For Contributors

go test ./...
go build -o codeforge.exe .

# Build release package
powershell -ExecutionPolicy Bypass -File .\scripts\build-release.ps1 -Version 0.1.77

For focused workspace tests:

go test ./internal/core/workspace

Further Reading