> ## Documentation Index
> Fetch the complete documentation index at: https://theagenticguy.github.io/opencodehub/llms.txt
> Use this file to discover all available pages before exploring further.
> Scoped bundles: [user-guide](https://theagenticguy.github.io/opencodehub/_llms-txt/user-guide.txt) · [mcp](https://theagenticguy.github.io/opencodehub/_llms-txt/mcp.txt) · [contributing](https://theagenticguy.github.io/opencodehub/_llms-txt/contributing.txt)

# Dev loop

The local dev loop is three commands once your toolchain is in place. This
page covers the toolchain pins, the full `mise` task catalogue, and when
to reach for the long-running `check:full` and `acceptance` targets.

## Toolchain pins

| Tool   | Version | How it gets installed |
|---|---|---|
| Node | 22 (CI also tests 24) | `mise.toml` — matches root `engines.node` |
| pnpm | 10.x (lockfile generated by 10.33.2) | `mise.toml` + `packageManager` field |
| Python | 3.12 | `mise.toml` — auxiliary tooling only |
| uv | latest | `mise.toml` — Python package manager |

You do not need `pyenv`, `nvm`, `direnv`, or a hand-rolled venv.
`mise` activates tools and environment variables when you `cd` into
the repo.

## Three-command dev loop

```bash title="Daily loop"
mise install                          # once per machine or after mise.toml changes
pnpm install --frozen-lockfile        # once per pnpm-lock.yaml change
mise run check                        # every time you want to know if your branch is green
```

`mise run check` runs lint, typecheck, test, and the banned-strings sweep
in a single chain and stops on the first failure. The equivalent
`pnpm run check` is wired to the same task.

## Individual checks

Run one gate at a time when you want a faster loop:

```bash
mise run lint               # Biome check across packages/**/src, packages/**/test, scripts
mise run typecheck          # tsc --noEmit across every workspace package
mise run test               # pnpm -r test (each package's `test` script)
mise run banned-strings     # scripts/check-banned-strings.sh
```

## Heavier gates

```bash
mise run check:full         # check + licenses + osv
mise run acceptance         # v1 Definition-of-Done gates
mise run smoke:mcp          # boot MCP server over stdio, assert tools/list
```

`check:full` adds the license allowlist (`license-checker-rseidelsohn`) and
the `osv-scanner` vulnerability scan against `pnpm-lock.yaml`. CI runs both
on every PR.

`acceptance` is the full v1.0 Definition-of-Done. Some gates are soft —
they log but do not block — because they depend on optional binaries
(semgrep, embedder weights) or measure timings on the local machine.

## Full task catalogue

Every task in `mise.toml`:

| Task                     | Purpose                                                                 |
|--------------------------|-------------------------------------------------------------------------|
| `install`                | `pnpm install --frozen-lockfile`                                       |
| `install:update`         | `pnpm install` — allows the lockfile to update                         |
| `bootstrap`              | `install`                                                              |
| `build`                  | `pnpm -r build` across every package                                   |
| `build:cli`              | Build only `@opencodehub/cli`                                          |
| `build:clean`            | Clean + full rebuild                                                   |
| `clean`                  | `pnpm -r clean`                                                        |
| `clean:all`              | Clean + delete `node_modules` everywhere                               |
| `cli:link`               | `pnpm link --global` — expose `codehub` system-wide for dev            |
| `cli:unlink`             | Reverse of `cli:link`                                                  |
| `cli:pack`               | Produce a distributable tarball of the CLI                             |
| `cli:install-global`     | Install the packed tarball globally with pnpm                          |
| `cli:uninstall-global`   | Remove the globally installed `codehub`                                |
| `test`                   | `pnpm -r test`                                                         |
| `lint`                   | `biome check .`                                                        |
| `lint:fix`               | `biome check --write .`                                                |
| `format`                 | `biome format --write .`                                               |
| `typecheck`              | `pnpm -r exec tsc --noEmit`                                            |
| `banned-strings`         | `scripts/check-banned-strings.sh`                                      |
| `licenses`               | License allowlist check (prod deps, private packages excluded)         |
| `osv`                    | `osv-scanner scan source --lockfile pnpm-lock.yaml`                    |
| `sarif:validate`         | Validate emitted SARIF against the Zod schema                          |
| `check`                  | `lint` + `typecheck` + `test` + `banned-strings`                       |
| `check:full`             | `check` + `licenses` + `osv`                                           |
| `acceptance`             | v1 Definition-of-Done gates (`scripts/acceptance.sh`)                  |
| `smoke:mcp`              | Boot the MCP server over stdio and assert `tools/list`                 |
| `commit`                 | Commitizen-guided Conventional Commit prompt                           |
| `envinfo`                | Print tool versions for bug reports                                    |
| `analyze`                | `codehub analyze` against the current repo                             |
| `status`                 | `codehub status`                                                       |
| `mcp`                    | Start the stdio MCP server                                             |

## Lefthook hooks

`lefthook install` (run once after `pnpm install`) wires three hooks:

| Hook        | Runs                                                    |
|-------------|---------------------------------------------------------|
| `pre-commit` | Biome autofix on staged `.ts/.tsx/.js/.jsx/.json/.jsonc` + banned-strings sweep |
| `commit-msg` | `commitlint --edit` on the draft message                |
| `pre-push`   | `tsc --noEmit` across packages + `pnpm -r test`         |

The pre-push hook is the last safety net before CI picks up your branch.
If it fails on a supposedly-unrelated test, see [Tenets](/opencodehub/contributing/overview/#tenets):
we fix it, we do not skip it.

## When to run `acceptance`

Before opening a PR that touches any of:

- The analyze pipeline (`packages/ingestion`, `packages/analysis`).
- Storage (`packages/storage`).
- The MCP server (`packages/mcp`).
- The graph-hash contract (anything that could affect determinism).
- `scripts/check-banned-strings.sh` or the CI workflows.

Otherwise `mise run check` is enough locally; CI will run the full matrix.

## See also

* [Commit conventions](/opencodehub/contributing/commit-conventions/)
* [Testing](/opencodehub/contributing/testing/)
* [Release process](/opencodehub/contributing/release-process/)