Skip to main content
rule CX Codex

3-cli-process — Claude Code rule: CLI process, channels and exit codes

3-cli-process sets the conventions for a CLI process: how it shuts down, which channel gets which output, and what exit code it returns.

MIT ★ 571 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/3-cli-process.md
Open on GitHub

What 3-cli-process does

A scoped rule for the command-line entry point. It loads for src/cli.ts and src/presentation/**/*.ts, so the rest of the repo is left alone.

Most of it is about shutdown. A floating promise or a bare unref() dies with the process, so background work has to go through an online command (ONLINE_COMMAND_PATHS in cli.ts), sit behind a timeout, or run detached. The fast path stays offline: read the cache, print, return. Side effects get asserted against the built binary, either in e2e or with pnpm smoke.

Output is split by channel: stdout for results and confirmations, stderr for debug lines, warnings and errors. A skipped or conflicting step is reported as warn rather than error. CLIOutput picks the level; rendering belongs to presentation/display/, decisions stay in the use case. Only two exit codes are allowed, 0 and 1, and a domain failure becomes a code through errorHandler.handle. Code under contexts/, kernel/ and runtime/ never calls process.exit — the biome-plugins/no-process-exit.grit plugin enforces that, and without it you are back to catching it in review.

What it helps with

  • Route command output between stdout and stderr
  • Keep background work alive until the process exits
  • Assign an exit code to a domain failure
  • Ban process.exit inside contexts/, kernel/ and runtime/
  • Verify a side effect against the built binary

Example prompts for the agent

  • Add a sync command to src/cli.ts and route its output the way 3-cli-process says
  • Audit src/cli.ts for floating promises and unref() calls nobody awaits
  • Why did the command exit with code 1? Walk the error handling against 3-cli-process

How to install 3-cli-process

Manually: put the files in place

.claude/rules/3-cli-process.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about 3-cli-process

How do I install 3-cli-process in Claude Code?

Place the rule file at .claude/rules/3-cli-process.md inside the project.

What does 3-cli-process do?

It sets the conventions for the CLI process: shutdown, output channels, formatting and exit codes.

Does 3-cli-process work outside Claude?

Yes. The same rule ships as .cursor/rules/3-cli-process.mdc for Cursor and as .github/instructions/3-cli-process.instructions.md for GitHub Copilot.

Source text

3-cli-process.md · MIT
---
description: Apply to the process, its channels and its exit codes; the CLI exits when the action resolves.
paths:
  - "src/cli.ts"
  - "src/presentation/**/*.ts"
---

# The CLI Process

## Exit

- Never fire and forget: `unref()` and floating promises die with the process.
- Deferred work rides an online command (`ONLINE_COMMAND_PATHS` in `cli.ts`), awaits behind a timeout, or runs detached.
- The hot path is offline: read cache, print, return.
- Assert a side effect against the built binary (e2e or `pnpm smoke`).

## Channels

- `stdout`: info, success, results.
- `stderr`: debug, warnings, errors.
- A conflict or skip is `warn`, never `error`.
- One-line final summary.

## Formatting

- `CLIOutput` routes by level, nothing else.
- Rendering: `presentation/display/`. Deciding: the use case.

## Exit codes

- `0`: did what was asked.
- `1`: thrown error, unhealthy `doctor`, guard needing a TTY.
- `errorHandler.handle` alone turns a domain failure into a code.
- A command may exit on a pre-use-case refusal: missing flag, non-interactive guard.
- Nothing under `contexts/`, `kernel/`, `runtime/` calls `process.exit` (`biome-plugins/no-process-exit.grit`).

© ai-driven-dev · MIT · ai-driven-dev/framework

Similar IDE rules

All IDE rules for Backend and APIs →

From the same set80

The whole set →
10-learn 10-learn — a skill for Claude Code, Cursor, and other platforms that records decisions, conventions, lessons, and code review findings as durable project knowledge. CX Codex +1 ★ 571repo stars 10-task 10-task — a skill that takes one bounded backlog task through framing, review and a final save. Reach for it when a piece of delivery work needs writing down, linking, ordering or closing. CX Codex +1 ★ 571repo stars 05-review 05-review inspects git diffs or implementation plans to confirm changes are ready to ship, pairing every issue with a fix. CX Codex +1 ★ 571repo stars 01-brainstorm The 01-brainstorm skill clarifies a rough idea through questions, then turns the discussion into a short brief. Use it when a request is ambiguous or you want to explore an idea together. CX Codex +1 ★ 571repo stars 02-project-memory 02-project-memory reads codebase architecture and decisions to build project memory and hook it into AI assistants. Useful for initial setups and drift audits. CX Codex +1 ★ 571repo stars 07-epic 07-epic is a Claude Code skill that shapes and reviews product backlog Epics. It checks readiness, resumes saved work, and supports approval before saving. CX Codex +1 ★ 571repo stars 09-defect 09-defect turns an observed product mismatch into a backlog defect: capture, assessment, then a confirmed write. CX Codex +1 ★ 571repo stars 06-agent-generate 06-agent-generate generates agent and subagent scaffolds across the AI coding tools configured in your project from a role prompt. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open