@manishbht/helpcode 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 helpcode contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# helpcode
+
+> A local agent that makes Claude.ai conversations efficient enough to ship real projects on a Pro subscription.
+
+[![CI](https://github.com/merolaagi/helpcode/actions/workflows/ci.yml/badge.svg)](https://github.com/merolaagi/helpcode/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/helpcode.svg)](https://www.npmjs.com/package/helpcode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+helpcode is a small local CLI for developers who use Claude.ai to write code. It does the mechanical work of an AI coding loop — selecting the right files, running tests, applying diffs, capturing errors — so the conversation turns you spend on Claude get used for actual thinking.
+
+**It does not call Claude.** You stay in Claude.ai, copy-paste with it as normal, and helpcode handles everything around that conversation. Optionally, it uses a **local model on your own machine** (via [Ollama](https://ollama.com)) to do the cheap reasoning — like working out which files matter for a task — so even that doesn't cost you a Claude turn.
+
+---
+
+## Why this exists
+
+A year ago, you could build a real piece of software in a day or two with Claude Code. The tool was new, the usage envelope was generous, and the iteration loop was fast.
+
+Today, Claude Code is significantly better — and significantly more in demand. Per-task pricing is fair for what you get, but at the $20/month Pro tier, a few iterations on a real codebase can consume more budget than a casual developer can sustain. Meanwhile, every routine "did the test pass?" or "which files are even relevant?" step burns frontier-model effort on work that doesn't need a frontier model.
+
+helpcode addresses both:
+
+- **For the developer:** each Claude conversation does more, because helpcode compresses context, structures prompts, and parses replies. One turn produces real progress instead of three turns of setup.
+- **For energy and cost:** routine plumbing runs locally — on a small model on your own hardware, or as plain deterministic code — instead of in a datacenter. Claude is reserved for actual reasoning. The right tool for the right job.
+
+This is the **two-layer model**: cheap local intelligence for the plumbing, expensive remote intelligence (Claude) for the thinking.
+
+---
+
+## What it does
+
+Six commands. No daemons, no watchers, no background processes.
+
+| Command | What it does |
+|---|---|
+| `helpcode init` | Detect your project — language, framework, test runner, and any local Ollama model — and write `.helpcode/project.json` |
+| `helpcode ask "..."` | Compose a structured prompt for Claude.ai. Picks the relevant files (with a local model if available), includes last test output, and a response-format spec |
+| `helpcode apply` | Paste Claude's reply; helpcode parses it, shows the planned changes, applies the diffs, runs tests |
+| `helpcode run "..."` | Run any shell command, get the output in compact form (perfect for pasting back to Claude) |
+| `helpcode status` | What does helpcode think the current state is? |
+| `helpcode reset` | Clear state and start fresh (your code is never touched) |
+
+---
+
+## The local-model layer (optional)
+
+If you have [Ollama](https://ollama.com) installed with a coding model pulled (e.g. `qwen2.5-coder`), `helpcode init` detects it automatically and `helpcode ask` will use it to **reason about which files are relevant** to your task — not just keyword-match them.
+
+The difference, on a real task:
+
+```bash
+$ helpcode ask "add a glucose variability calculation" --explain-selection
+selecting files (local model: qwen2.5-coder:7b)...
+✓ selected 2 file(s) via local model
+  src/analyze.py — contains the time-in-range function a variability calc would extend
+  tests/test_analyze.py — where the new calculation's tests belong
+```
+
+A plain keyword search would match files that literally contain "glucose." A local model understands that a *variability* calculation naturally extends the *time-in-range* function already in `analyze.py` — reasoning the keyword approach can't do.
+
+**It never gets in the way.** If Ollama isn't installed, isn't running, times out, or returns nothing useful, helpcode silently falls back to a fast keyword heuristic. The local model is a free upgrade when present, never a dependency.
+
+Useful flags:
+- `--no-llm` — force the keyword heuristic for this run
+- `--explain-selection` — show why each file was chosen
+
+Configure the model in `.helpcode/project.json`:
+
+```jsonc
+"ollama": {
+  "enabled": true,
+  "model": "qwen2.5-coder:7b",   // or 14b / deepseek-coder-v2 for more reasoning
+  "host": "http://localhost:11434",
+  "timeoutMs": 20000
+}
+```
+
+---
+
+## Install
+
+```bash
+npm install -g helpcode
+```
+
+Requires Node.js 20 or later. Tested on macOS, Linux, and Windows.
+
+You don't need an API key. You don't need to sign up for anything. helpcode never calls Claude or any other remote AI service — it just helps you talk to Claude.ai more efficiently. The only optional integration is a local Ollama server on your own machine.
+
+---
+
+## A typical session
+
+```bash
+# In your project, once:
+$ helpcode init
+✓ Initialised .helpcode/project.json
+
+Detected:
+  language:    python
+  framework:   Flask
+  source dirs: app, tests
+  test cmd:    pytest -q --tb=short
+  ollama:      enabled, model: qwen2.5-coder:7b
+
+# Start a task:
+$ helpcode ask "fix the login bug where uppercase emails fail"
+selecting files (local model: qwen2.5-coder:7b)...
+✓ selected 2 file(s) via local model
+
+────────────────────────────────────────────────────────────
+  COPY EVERYTHING BELOW INTO CLAUDE.AI
+────────────────────────────────────────────────────────────
+## Project context
+- Language: python
+- Framework: Flask
+
+## Files (2)
+### `app/auth.py`
+... (relevant code)
+
+## My task
+fix the login bug where uppercase emails fail
+
+## Please respond in this format
+...
+```
+
+You paste that into Claude.ai. Claude replies in the structured format. You paste the reply back:
+
+```bash
+$ helpcode apply
+# (paste Claude's reply, press Ctrl-D)
+
+Plan:
+  Lowercase the email before lookup in USERS.
+
+Files to change:
+  • app/auth.py
+
+Apply these changes? [y/N] y
+✓ patched app/auth.py
+running: pytest tests/test_auth.py -v
+Exit: 0    Time: 0.32s
+3 passed in 0.32s
+
+✓ Tests pass. Ready to commit when you are.
+```
+
+Each turn with Claude does real work — no re-pasting the test output, the imports, and your Python version every time.
+
+---
+
+## What it is not
+
+- **Not an agent that calls Claude.** No API key, no surprise costs. You stay in the loop.
+- **Not a replacement for Claude Code** — which is excellent at autonomous, multi-step work. helpcode is for people who'd rather stay inside their Pro subscription.
+- **Not a sandbox.** It runs your code with your normal permissions. Don't run code you don't trust.
+- **Not multi-provider orchestration — yet.** Routing across several models with budget caps is the v0.3 horizon. See [`docs/ROADMAP.md`](docs/ROADMAP.md).
+
+---
+
+## Privacy
+
+Everything stays on your machine. helpcode makes no network calls except to npm (once, during install) and — if you enable it — to a local Ollama server on `localhost`. It never sends your code to any remote service. Read [`docs/PRIVACY.md`](docs/PRIVACY.md) for the full breakdown.
+
+The only thing that leaves your machine is whatever **you** paste into Claude.ai, which is your existing relationship with Anthropic.
+
+---
+
+## Contributing
+
+Yes please. helpcode is small enough that the entire CLI is readable in an evening, and the architecture is explicitly designed for community evolution. Start with:
+
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to set up and where to start
+- [`ARCHITECTURE.md`](ARCHITECTURE.md) — the design doc this is built from
+- [`docs/ROADMAP.md`](docs/ROADMAP.md) — what's planned and why
+
+Good first issues are labelled [`good first issue`](https://github.com/merolaagi/helpcode/issues?q=label%3A%22good+first+issue%22) on the issue tracker.
+
+---
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/dist/bin/helpcode.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Entry shim for the published `helpcode` command.
+ */
+export {};

package/dist/bin/helpcode.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Entry shim for the published `helpcode` command.
+ */
+import { run } from '../src/index.js';
+run(process.argv.slice(2)).then(code => process.exit(code), err => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=helpcode.js.map

package/dist/bin/helpcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpcode.js","sourceRoot":"","sources":["../../bin/helpcode.ts"],"names":[],"mappings":";AACA;;GAEG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAEtC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC1B,GAAG,CAAC,EAAE;IACJ,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CACF,CAAC"}

package/dist/src/commands/apply.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `helpcode apply` — parse Claude's reply (from stdin), apply diffs,
+ * run the test command. Updates state with the verdict.
+ *
+ * v0.1 is intentionally conservative:
+ *   - Shows planned changes before applying
+ *   - Asks for confirmation (unless --yes)
+ *   - On any diff failure, stops and reports — does NOT roll back yet
+ *     (v0.2 will add rollback via core/rollback.ts)
+ */
+export interface ApplyOptions {
+    yes?: boolean;
+    dryRun?: boolean;
+}
+export declare function handleApply(opts?: ApplyOptions): Promise<number>;

package/dist/src/commands/apply.js

@@ -0,0 +1,195 @@
+/**
+ * `helpcode apply` — parse Claude's reply (from stdin), apply diffs,
+ * run the test command. Updates state with the verdict.
+ *
+ * v0.1 is intentionally conservative:
+ *   - Shows planned changes before applying
+ *   - Asks for confirmation (unless --yes)
+ *   - On any diff failure, stops and reports — does NOT roll back yet
+ *     (v0.2 will add rollback via core/rollback.ts)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadState, saveState } from '../core/state.js';
+import { loadProjectConfig } from '../core/project.js';
+import { parseClaudeResponse, validateParsedResponse } from '../core/parser.js';
+import { applyLinePatch } from '../core/patcher.js';
+import { runShellCommand } from '../core/tools.js';
+import { classifyRunFailure } from '../lib/runclass.js';
+import { truncateLines, extractTraceback } from '../lib/compress.js';
+import { readStdin, confirm, c, log } from '../lib/ui.js';
+import { HelpcodeError } from '../lib/errors.js';
+export async function handleApply(opts = {}) {
+    const state = loadState();
+    if (!state.currentTask) {
+        log.err('No current task. Run `helpcode ask "<task>"` first.');
+        return 1;
+    }
+    const task = state.currentTask;
+    // Get Claude's response. Prefer stdin; fall back to .helpcode/response.txt.
+    const raw = await getResponseText();
+    if (!raw.trim()) {
+        log.err('No input received.');
+        log.dim('Paste Claude\'s reply and press Ctrl-D, or save it to .helpcode/response.txt first.');
+        return 1;
+    }
+    task.lastResponseRaw = raw;
+    const parsed = parseClaudeResponse(raw);
+    if (parsed.parseWarning) {
+        log.warn('Claude\'s reply doesn\'t match the expected format.');
+        log.dim('Helpcode expects sections like `## PLAN`, `## DIFF: <file>`, `## TEST`.');
+        log.dim('Save the reply, fix the format, and re-run `helpcode apply`.');
+        task.status = 'failed';
+        saveState(state);
+        return 1;
+    }
+    if (parsed.repairsApplied) {
+        log.dim('(auto-repaired copy-paste corruption in Claude\'s reply — review the plan below carefully)');
+    }
+    const issues = validateParsedResponse(parsed);
+    if (issues.length > 0) {
+        log.err('Response failed validation:');
+        for (const i of issues)
+            log.err('  ' + i);
+        task.status = 'failed';
+        saveState(state);
+        return 1;
+    }
+    showPlan(parsed);
+    if (opts.dryRun) {
+        log.dim('--dry-run: not applying anything.');
+        return 0;
+    }
+    if (!opts.yes) {
+        const ok = await confirm('Apply these changes?');
+        if (!ok) {
+            log.dim('Cancelled.');
+            return 0;
+        }
+    }
+    task.status = 'applying';
+    saveState(state);
+    const applied = [];
+    let allOk = true;
+    for (const diff of parsed.diffs) {
+        try {
+            const r = applyLinePatch(diff.filepath, diff.patchLines);
+            applied.push({
+                filepath: r.filepath,
+                hunks: r.hunksApplied,
+                ok: true,
+                created: r.created,
+            });
+            log.ok(`patched ${r.filepath}${r.created ? ' (new file)' : ''}`);
+        }
+        catch (e) {
+            const msg = e instanceof HelpcodeError ? e.message : e.message;
+            const hint = e instanceof HelpcodeError ? e.hint : '';
+            log.err(`failed: ${diff.filepath} — ${msg}`);
+            if (hint)
+                log.dim('  ' + hint);
+            applied.push({
+                filepath: diff.filepath,
+                hunks: 0,
+                ok: false,
+                created: false,
+            });
+            allOk = false;
+            break; // stop on first failure for v0.1
+        }
+    }
+    task.lastDiffsApplied = applied;
+    if (!allOk) {
+        task.status = 'failed';
+        saveState(state);
+        log.warn('Some patches failed. Files written before the failure are still on disk.');
+        log.dim('v0.2 will add automatic rollback. For now, use `git checkout -- <file>` or your editor\'s undo.');
+        return 1;
+    }
+    // Run the test command Claude suggested, or the project default
+    const config = loadProjectConfig();
+    const testCmd = parsed.testCommand ?? config.testCommand;
+    if (!testCmd) {
+        log.dim('No test command available — skipping test run.');
+        task.status = 'resolved';
+        saveState(state);
+        log.ok('Done.');
+        return 0;
+    }
+    task.status = 'testing';
+    saveState(state);
+    log.dim(`running: ${testCmd}`);
+    const result = await runShellCommand(testCmd, { timeoutSecs: 120 });
+    const testReport = formatTestReport(testCmd, result);
+    task.lastTestOutput = testReport;
+    console.log();
+    console.log(testReport);
+    if (result.exitCode === 0) {
+        task.status = 'resolved';
+        saveState(state);
+        console.log();
+        log.ok('Tests pass. Ready to commit when you are.');
+        return 0;
+    }
+    else {
+        task.status = 'failed';
+        saveState(state);
+        console.log();
+        const classification = classifyRunFailure(result);
+        if (classification.kind === 'test') {
+            log.warn(classification.message);
+            log.dim(classification.hint);
+        }
+        else {
+            // setup or timeout: not a Claude problem
+            log.warn(classification.message);
+            if (classification.hint)
+                log.dim(classification.hint);
+        }
+        return result.exitCode;
+    }
+}
+async function getResponseText() {
+    // If stdin is a TTY and there's a saved response, prefer that
+    const savedPath = path.join('.helpcode', 'response.txt');
+    if (process.stdin.isTTY && fs.existsSync(savedPath)) {
+        log.dim(`using saved response from ${savedPath}`);
+        return fs.readFileSync(savedPath, 'utf-8');
+    }
+    return readStdin();
+}
+function showPlan(parsed) {
+    console.log();
+    console.log(c.bold('Plan:'));
+    console.log('  ' + parsed.plan.split('\n').join('\n  '));
+    console.log();
+    console.log(c.bold('Files to change:'));
+    for (const d of parsed.diffs) {
+        console.log(`  ${c.cyan('•')} ${d.filepath}`);
+    }
+    if (parsed.testCommand) {
+        console.log();
+        console.log(c.bold('Test command:'));
+        console.log(`  ${parsed.testCommand}`);
+    }
+    if (parsed.notes) {
+        console.log();
+        console.log(c.bold('Notes from Claude:'));
+        console.log('  ' + parsed.notes.split('\n').join('\n  '));
+    }
+}
+function formatTestReport(cmd, result) {
+    const parts = [];
+    parts.push(`$ ${cmd}`);
+    parts.push(`Exit: ${result.exitCode}    Time: ${(result.durationMs / 1000).toFixed(2)}s`);
+    if (result.stdout.trim()) {
+        parts.push('--- stdout ---');
+        parts.push(truncateLines(result.stdout.trimEnd(), 40, 'stdout lines'));
+    }
+    if (result.stderr.trim()) {
+        parts.push('--- stderr ---');
+        parts.push(extractTraceback(result.stderr));
+    }
+    return parts.join('\n');
+}
+//# sourceMappingURL=apply.js.map

package/dist/src/commands/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../../src/commands/apply.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/ask.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `helpcode ask "<task>"` — assemble a structured prompt for Claude.ai
+ * based on the project state and selected files. Prints a paste block.
+ */
+export interface AskOptions {
+    files?: string[];
+    /** Force the heuristic selector even if Ollama is enabled. */
+    noLlm?: boolean;
+    /** Print the reason each file was selected. */
+    explainSelection?: boolean;
+}
+export declare function handleAsk(taskDescription: string, opts?: AskOptions): Promise<number>;

package/dist/src/commands/ask.js

@@ -0,0 +1,93 @@
+/**
+ * `helpcode ask "<task>"` — assemble a structured prompt for Claude.ai
+ * based on the project state and selected files. Prints a paste block.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadProjectConfig } from '../core/project.js';
+import { loadState, saveState, createTask } from '../core/state.js';
+import { selectFilesWithStrategy } from '../core/selector.js';
+import { buildPrompt } from '../core/prompt.js';
+import { printPasteBlock, log, c } from '../lib/ui.js';
+const STATE_DIR = '.helpcode';
+export async function handleAsk(taskDescription, opts = {}) {
+    if (!taskDescription || !taskDescription.trim()) {
+        log.err('Usage: helpcode ask "<task description>"');
+        return 1;
+    }
+    const config = loadProjectConfig();
+    const state = loadState();
+    // If there's no current task, or the user is starting fresh, create one
+    let task = state.currentTask;
+    if (!task || task.status === 'resolved' || task.status === 'failed') {
+        task = createTask(taskDescription);
+        state.currentTask = task;
+    }
+    else {
+        task.iterations += 1;
+    }
+    // Resolve files: explicit override, else LLM-or-heuristic strategy
+    let selectedFiles;
+    if (opts.files && opts.files.length > 0) {
+        selectedFiles = opts.files
+            .map(f => path.resolve(f))
+            .filter(f => {
+            if (!fs.existsSync(f)) {
+                log.warn(`File not found, skipping: ${f}`);
+                return false;
+            }
+            return true;
+        });
+        if (opts.explainSelection) {
+            for (const f of selectedFiles) {
+                log.dim(`  ${path.relative(config.root, f)} — explicitly provided via --files`);
+            }
+        }
+    }
+    else {
+        if (config.ollama?.enabled && !opts.noLlm) {
+            log.dim(`selecting files (local model: ${config.ollama.model})...`);
+        }
+        const result = await selectFilesWithStrategy(taskDescription, config, {
+            forceHeuristic: opts.noLlm,
+        });
+        selectedFiles = result.files.map(f => f.filepath);
+        if (result.strategy === 'llm') {
+            log.ok(`selected ${result.files.length} file(s) via local model`);
+        }
+        else if (result.fallbackReason) {
+            log.dim(`local-model selection unavailable (${result.fallbackReason}) — used keyword heuristic`);
+        }
+        if (opts.explainSelection) {
+            for (const f of result.files) {
+                log.dim(`  ${path.relative(config.root, f.filepath)} — ${f.reason}`);
+            }
+        }
+    }
+    if (selectedFiles.length === 0) {
+        log.warn('No relevant files found. The prompt will contain context only.');
+        log.dim('Tip: pass --files <paths> to include specific files.');
+    }
+    const prompt = buildPrompt({
+        taskDescription,
+        selectedFiles,
+        lastTestOutput: task.lastTestOutput,
+        config,
+    });
+    // Persist
+    task.lastPrompt = prompt;
+    task.status = 'awaiting_paste';
+    saveState(state);
+    // Also save the prompt to a file the user can re-copy from
+    const pendingPath = path.join(STATE_DIR, 'pending.txt');
+    fs.writeFileSync(pendingPath, prompt, 'utf-8');
+    printPasteBlock(prompt);
+    console.log();
+    log.dim(`(saved a copy at ${pendingPath})`);
+    log.dim(`(~${Math.round(prompt.length / 4)} tokens approx)`);
+    console.log();
+    console.log(`${c.bold('Next:')} paste this into Claude.ai, copy the reply, then run:`);
+    console.log(`  ${c.cyan('helpcode apply')}`);
+    return 0;
+}
+//# sourceMappingURL=ask.js.map

package/dist/src/commands/ask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.js","sourceRoot":"","sources":["../../../src/commands/ask.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/init.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `helpcode init` — detect the project, write .helpcode/project.json,
+ * make sure .helpcode/ is gitignored.
+ */
+export interface InitOptions {
+    force?: boolean;
+    /**
+     * Skip the Ollama liveness probe. Used by tests so they never do real
+     * network I/O. In normal use this is always false.
+     */
+    skipOllamaDetection?: boolean;
+}
+export declare function handleInit(opts?: InitOptions): Promise<number>;