Turn natural language into reviewed, validated code patches in seconds. Write less. Ship safer.
npx human-to-code .
Create a reusable TypeScript function that:
- accepts an array of numbers
- returns a new sorted array
- never mutates the input
sort.ts
export function sortNumbers(
items: number[],
): number[] {
return [...items].sort((a, b) => a - b);
}generated TypeScript from human intent
sort.ts (before)
export type SortOrder = "asc" | "desc";
/* @human
Implement sortNumbers with:
- immutable output
- ascending and descending order
*/export type SortOrder = "asc" | "desc";
export function sortNumbers(items: number[], order: SortOrder) {
const sorted = [...items].sort((a, b) => a - b);
return order === "desc" ? sorted.reverse() : sorted;
}marker replaced in sort.ts
sort.js (before)
/* @human
Create sortBy that:
- accepts an array and selector function
- returns a new array
- keeps the original array unchanged
*/export function sortBy(items, select) {
return [...items].sort((a, b) => {
const left = select(a);
const right = select(b);
return left < right ? -1 : left > right ? 1 : 0;
});
}marker replaced in sort.js
sort.py (before)
from collections.abc import Iterable
""" @human
Implement sort_numbers:
- accept an Iterable of numbers
- return a new ascending list
- never mutate the input
"""from collections.abc import Iterable
def sort_numbers(
items: Iterable[float],
) -> list[float]:
return sorted(items)marker replaced in sort.py
sort.rs (before)
#[derive(Clone)]
pub struct Score {
pub value: i32,
}
/* @human
Implement sort_scores:
- take a borrowed slice
- return a new Vec
- sort by value ascending
*/#[derive(Clone)]
pub struct Score {
pub value: i32,
}
pub fn sort_scores(scores: &[Score]) -> Vec<Score> {
let mut sorted = scores.to_vec();
sorted.sort_by_key(|score| score.value);
sorted
}marker replaced in sort.rs
10 languages through the direct path today, grounded profiles for React, NestJS, FastAPI & Rust — the rest are on the roadmap
Local & private by default — no code leaves your machine until you choose a remote provider and consent.
human-to-code runs on any platform supported by Node.js 24+. Make sure Node.js is installed on your system before continuing; no global installation of human-to-code is required.
The default config targets your local Ollama on http://localhost:11434 with qwen2.5-coder:7b. human-to-code never pulls a model for you, so pull it once.
Install Ollama for your platform, then run:
ollama pull qwen2.5-coder:7bCredentials are environment-only — the config stores the variable name (OPENAI_API_KEY), never the key itself.
Set OPENAI_API_KEY in your system environment using your platform's standard method.
--init writes a complete, schema-versioned human-to-code.config.json and never overwrites an existing one. Treat it as a reviewable template.
npx human-to-code --init .The generated file already targets local Ollama — no edits needed:
{
"schemaVersion": 1,
"provider": {
"name": "ollama",
"model": "qwen2.5-coder:7b"
},
"privacy": { "remoteProviderConsent": false }
}Edit the provider and privacy blocks. Remote generation is blocked until you set conservative pricing bounds and consent:
{
"schemaVersion": 1,
"provider": {
"name": "openai",
"model": "gpt-4o-2024-08-06",
"apiKeyEnv": "OPENAI_API_KEY",
"pricing": {
"inputUsdPerMillionTokens": 25,
"outputUsdPerMillionTokens": 100
}
},
"privacy": { "remoteProviderConsent": true },
"budgets": { "maxCostUsd": 25 }
}Set the rates at or above the real published rates for your exact model — they are a fail-closed budget guard, not a live price feed.
Create a .human file, or drop an inline @human marker into an existing source file.
# sort-list.human
Create a function that returns a new sorted
copy of a list, with a docstring.
Before sending anything to a remote provider, inspect the complete outbound envelope — every file, range, hash, and redaction. Remote providers get no follow-up requests, so this preview is the whole payload.
npx human-to-code context sort-list.strict.human.json --explainRun the guided command. It analyzes the project, shows a receipt, and asks before writing — nothing is generated on --dry-run.
npx human-to-code .For a reviewed, sandbox-validated patch against a recognized React, NestJS, FastAPI, or Rust project, use npx human-to-code guided . instead — it drafts a change contract for your review first.
Three ways to use it — pick the one that fits your workflow.
Write your request in a *.human file; the generated code lands in a sibling file named after it (extension follows your configured language).
# greet.human
Write a function that takes a name and returns
a friendly greeting, with a docstring.
$ npx human-to-code .
✓ wrote greet.pyDrop a marker inside an existing source file using its native block syntax — for example, /* @human … */ for a multiline TypeScript or JavaScript request and """ @human … """ in Python. The marker region is replaced in place with generated code.
// utils.ts
// @human debounce helper with cancel()
$ npx human-to-code .
✓ wrote utils.tsFor reviewed, sandbox-validated patches against a recognized React, NestJS, FastAPI, or Rust project, use guided: it drafts a change contract for your review before anything is generated.
$ npx human-to-code guided .
Wrote add-health-route.strict.human.json
Review the contract, then rerun to generate
a validated, reviewable patch. Apply is a
separate, explicit step.Every generation shows a receipt — files, provider, model — and asks before writing. Nothing is written on --dry-run.
The essentials — the full README covers everything.
# default: discover .human files and @human
# markers, show a receipt, write code
npx human-to-code .
# create a reviewable config (never overwrites)
npx human-to-code --init .
# reviewed contract → validated patch
npx human-to-code guided .Requires Node.js 24+. The default provider is loopback-local Ollama with qwen2.5-coder:7b — no code leaves your machine until you configure a remote provider and consent.
OpenAI and Ollama (local, Cloud, or a trusted custom endpoint) are the supported providers. Credentials are environment-only — the config stores a variable name like OPENAI_API_KEY, never a key. Remote generation requires explicit consent and reviewed pricing bounds.
human-to-code . — direct .human/@human generation with receiptguided — analyze → contract → grounded patch → sandbox validationanalyze — static multi-workspace project profileplan / generate / validate — the pipeline, step by stepapply / rollback — explicit, hash-checked, reversiblecheck — verify every .human has a current contractThe guided pipeline scans for secrets before any provider call, validates in a no-network container sandbox, and only an explicit apply of a VERIFIED run touches your working tree. Read SECURITY.md and ARCHITECTURE.md.