Quick start · How it works · CLI · Configuration · Config reference · Contributing · Community

You know the loop: you're in your IDE, you jump over to ChatGPT, paste some context, copy the answer back, fix the indentation. Again. human-to-code removes that loop. Write a comment saying what you want: ```ts // @human add a function named health that returns { status: 200 } ``` Then run `npx human-to-code .`. The comment becomes the code, right there in your file. Starting from scratch? Don't open a `.ts` or a `.py`. Write a `file.human` instead, one plain-English line at a time, and it compiles to real TypeScript, JavaScript, Python, Rust, HTML, or CSS. Pseudocode that actually runs. Either way you keep your grip on the codebase. You're not handing the whole thing to an agent and hoping it comes back with something you recognize. ## How it works

Three steps: write intent as an @human comment, review the receipt showing provider, model and output paths, then get code that was validated before it was written

You say what you want. The tool shows you what it plans to do and stops. After you confirm, it generates each target, checks the result against the rest of your project, and only then writes. ### What you get

Your codebase, not a blank slate ProjectMemory hands each request your real file tree, the planned outputs, and compact contracts for related files. Generated code imports what exists instead of inventing a module.	Validated before it is written TypeScript and opted-in JavaScript go through the TypeScript compiler against your unchanged baseline. Other languages get deterministic structural checks. Inline edits are diffed, so errors that were already there are never blamed on the new code.
Local-first and private by default A fresh install talks to loopback Ollama. Remote providers stay blocked until you set `privacy.remoteProviderConsent` yourself. Credentials live in environment variables, and the config only ever names them.	No surprise requests The receipt shows the planned request count before you confirm, with classification, shared contract, todo, and coding passes counted separately and conditional repair ceilings listed on top.
Cross-file coherence A shared contract settles names once per run. Static reference checks then catch a stylesheet selector no markup matches, or a handler nothing calls, without spending another request.	Guarded writes Whole-file output lands as one rollback-protected batch. Inline replacements check exact bytes first, so a file that changed under you is skipped rather than clobbered.

## Quick start ```bash npx human-to-code . ``` The `.` is the folder to scan, not permission to rewrite it. A default run: 1. **Scans** for `.human` files and inline `@human` markers. It never imports your application modules and never executes your project config. 2. **Warns** about marker-shaped requests in file types it can't handle, and refuses a `.human` request whose output file already exists. Ignored directories and symlinks stay out of discovery. 3. **Prints a receipt**: the languages this worklist selected, the provider, the model, the request count, and every source-to-output path. 4. **Waits.** Confirm generation first. While the agent works, each accepted candidate appears as an inline terminal diff with red removals and green additions. 5. **Reviews, then writes.** After validation, the CLI prints the authoritative combined diff and separately asks whether to apply it. Nothing is written before that approval. `-y` skips both prompts for automation. You don't need a configured provider to scan and preview. A default run picks loopback Ollama with `qwen2.5-coder:7b`, so a fresh `npx human-to-code .` sends nothing anywhere. That model does have to be installed already, because the tool will never pull one for you. To use a different local model, OpenAI, or Ollama Cloud, write a config first: ```bash npx human-to-code --init . ``` `--init` won't overwrite a config you already have. Remote generation always needs a config file, because `privacy.remoteProviderConsent` starts at `false` and no CLI flag can flip it. Converting an inline marker in place: ```bash printf '// @human add a function named health that returns { status: 200 }\n' > health.ts npx human-to-code . --yes --model qwen2.5-coder:7b # health.ts now has the function where the marker used to be. ``` From a source checkout: ```bash npm ci npm run build node dist/cli.js . ``` Node.js 24 or newer is required. ## Generation engine

Discovery and the receipt make no provider requests. Your confirmation is the gate. After it the run plans, generates, validates and writes, with one bounded repair before a group is rejected

The host stays in control and the model only proposes code or requests bounded read-only evidence. Candidate diffs are lifecycle output, not writes; the application layer remains paused until final human approval. Each inline marker gets a small classification request, then edit turns return raw source code. The host extracts exactly one code artifact, constructs the strict `{schemaVersion, code}` envelope itself, and validates it locally. Whole `.human` files go straight to coding. On loopback Ollama the model may call `request_context` before answering; tool use is optional, so a model can still finish without a tool call. ### What it picks up Inline discovery covers `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.html`, `.htm`, `.css`, `.py`, `.rs`, `.go`, `.java`, `.rb`, `.cs`, `.cpp`, `.cc`, `.c`, `.h`, and `.hpp`. A marker-shaped request in any other regular file under 1 MiB gets reported as unsupported rather than silently skipped. Ignored directories, dot directories, and symlinks stay out of the walk, and oversized unsupported files are never opened just to produce a notice. The scanner is lexical. It reads `// @human` and `# @human` line comments (including consecutive `#` comment lines after a Python marker), single-line and multiline `/* @human ... */` blocks, decorated JSDoc comments, and `` in HTML. Inside HTML it also reads the JavaScript and CSS comment forms in `

Your codebase, not a blank slate ProjectMemory hands each request your real file tree, the planned outputs, and compact contracts for related files. Generated code imports what exists instead of inventing a module.	Validated before it is written TypeScript and opted-in JavaScript go through the TypeScript compiler against your unchanged baseline. Other languages get deterministic structural checks. Inline edits are diffed, so errors that were already there are never blamed on the new code.
Local-first and private by default A fresh install talks to loopback Ollama. Remote providers stay blocked until you set `privacy.remoteProviderConsent` yourself. Credentials live in environment variables, and the config only ever names them.	No surprise requests The receipt shows the planned request count before you confirm, with classification, shared contract, todo, and coding passes counted separately and conditional repair ceilings listed on top.
Cross-file coherence A shared contract settles names once per run. Static reference checks then catch a stylesheet selector no markup matches, or a handler nothing calls, without spending another request.	Guarded writes Whole-file output lands as one rollback-protected batch. Inline replacements check exact bytes first, so a file that changed under you is skipped rather than clobbered.