ineedcodes 0.2.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 iNeedCodes
+Copyright (c) 2026 0xyas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,122 +1,120 @@
 <div align="center">
 
-<img src="docs/assets/ineed-logo.svg" alt="ineed: your terminal, now autonomous" width="640"/>
+<img src="https://raw.githubusercontent.com/ineedcodes/ineedcodes/main/assets/logo.svg" alt="ineed" width="320">
 
-**ineed**
+**Your terminal, now autonomous.**
+
+You say what you want. ineed reads the files, writes the code, runs the commands, checks the output, and fixes what breaks.
 
 [![npm](https://img.shields.io/npm/v/ineedcodes.svg)](https://www.npmjs.com/package/ineedcodes)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org)
-[![platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]()
-
-[ineed.codes](https://ineed.codes) &nbsp;·&nbsp; [ineed.web.id](https://ineed.web.id) &nbsp;·&nbsp; [Contributing](CONTRIBUTING.md)
+[![node](https://img.shields.io/node/v/ineedcodes.svg)](https://nodejs.org)
+[![stars](https://img.shields.io/github/stars/ineedcodes/ineedcodes?style=social)](https://github.com/ineedcodes/ineedcodes)
 
 </div>
 
----
-
-## What is ineed?
-
-A CLI AI agent. You say what you want in plain language. It does the work:
-reads code, runs commands, edits files, uses Git, runs tests, and shows you
-real proof that it worked.
+## Install
 
 ```bash
-ineed "fix the build errors in this project"
+npm install -g ineedcodes
 ```
 
-Made for beginners. Every step is narrated in plain English, nothing is
-hidden, and success is never claimed without evidence. Watch how it works,
-learn the workflow: that is vibecoding.
+Works on Linux, macOS, and Windows (PowerShell and cmd). Needs Node.js 20 or newer.
 
-## Install
+## First open
 
-```bash
-npm install -g ineedcodes
 ```
+$ ineed
 
-Package name is `ineedcodes`. The command you type is `ineed`.
+Welcome to ineed - let's connect you to an AI provider. You only do this once.
+Any OpenAI-compatible API works: OpenAI, OmniRoute, LM Studio, Ollama, vLLM, and more.
 
-## First run
-
-```bash
-ineed
+1. API base URL (example: https://api.openai.com/v1): https://api.openai.com/v1
+2. API key (input hidden): ********
+   Connected. 41 models available.
+3. Model id (Enter = gpt-4o-mini):
+   Works. Replied: OK
+   Saved to ~/.ineedcodes/config.json. You will not be asked again.
 ```
 
-A setup wizard asks three things: pick a provider, paste an API key, choose
-a model from a live list. Saved once in `~/.ineedcodes/config.json`. Any
-OpenAI-compatible API works: OpenAI, iNeed API, OmniRoute, LM Studio,
-Ollama, vLLM, and more.
+Pick your provider, paste your key, choose a model. Done once, never asked again.
 
-## Use it
+## Use
 
 ```bash
-ineed                        # interactive session in this folder
-ineed "explain this repo"    # one-shot task
-ineed --resume               # continue your last session
+ineed                          # session
+ineed "fix the build errors"   # one-shot task
 ```
 
-Then just talk:
+Then just talk.
+
+```
+ineed › fix the failing tests and tell me what was wrong
+ineed › build me a telegram bot that echoes messages, test it, then commit
+ineed › explain this repository like I am a beginner
+```
 
-- *Fix the authentication bug.*
-- *Get this GitHub project running.*
-- *Why is this API failing? Fix it and prove it.*
-- *Make this README sound human.*
+The agent decides what it needs: list files, read code, search, edit, run shell commands, verify the result, and report back with evidence.
 
-## Learn while you work
+## Session shortcuts
 
-| You type | You learn |
+| command | what it does |
 |---|---|
-| a plain-language goal | how agents plan and verify work |
-| `/plan` then `/build` | why reading before changing matters |
-| `/context` | how token budgets and compaction work |
-| `/think high` on a hard bug | how reasoning depth changes results |
-| `/init` | how AGENTS.md instructions shape an agent |
-| `/doctor` | what a healthy setup looks like |
-
-Slash commands are optional. Plain language always works:
-`/help` `/model` `/plan` `/build` `/think` `/context` `/memory` `/skills`
-`/permissions` `/init` `/doctor` `/resume` `/clear` `/copy` `/exit`
-
-> New to AI coding? Free tutorials and a curated list of free AI resources:
-> [ineed.web.id](https://ineed.web.id). No signup, no paywall.
-
-## What is inside
-
-- **Agent runtime**: an iterative loop: reason, call a tool, observe the real
-  result, adapt, verify. Plan mode (read only) and build mode. Reasoning
-  effort from low to high.
-- **Tools**: filesystem, search (ripgrep with fallback), shell, Git, web, and
-  a native MCP client. Tools take JSON, return JSON.
-- **Memory**: [ICM](https://github.com/rtk-ai/icm), one database per project.
-  Conventions, solved errors, and decisions survive across sessions.
-- **Skills**: portable `SKILL.md` files. Built-ins: `boost` (isolated worktree
-  plus independent verification) and `humanizer` (natural prose rewriting).
-- **Permissions**: `ask`, `workspace`, or `autonomous`. Destructive, remote,
-  and secret operations always need approval.
-- **Secrets**: `.env` files, SSH keys, and tokens never reach model context.
-- **Providers**: any OpenAI-compatible API. No lock-in.
-
-## Project layout
+| `/model` | pick a model from your provider |
+| `/plan` | read-only mode, the agent suggests but changes nothing |
+| `/build` | default mode, the agent makes real changes |
+| `/reason` | toggle reasoning effort low/high |
+| `/clear` | forget the current conversation |
+| `/setup` | redo provider setup |
+| `/exit` | quit |
+
+Shortcuts are optional. Normal language always works.
+
+## How it works
 
 ```
-packages/
-  core/    tools, LLM providers, ICM adapter, permissions, context, skills
-  agent/   agent loop, lead agent, orchestrator, boost
-  cli/     TUI, setup wizard, slash commands
+your words
+    |
+objective -> recall context -> pick tool -> real action -> observe result
+    |                                                          |
+    +------------- repeat until verified ----------------------+
+    |
+report with evidence
 ```
 
-## Contributing
+Not a chatbot that prints code. A loop that does the work, checks the results, and shows you the evidence.
 
-This project teaches beginners, so contributions should keep that spirit.
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+### Tools
 
----
+| tool | does |
+|---|---|
+| `list_files` | map the project |
+| `read_file` | read code and configs |
+| `search_text` | find anything, fast |
+| `write_file` | create files |
+| `edit_file` | targeted patch, not a rewrite |
+| `delete_file` | remove a file |
+| `shell` | build, test, install, git, anything |
 
-<div align="center">
+### Safety
 
-MIT licensed.
-[ineed.codes](https://ineed.codes) is the product.
-[ineed.web.id](https://ineed.web.id) is where you learn AI, free.
+- Secrets (.env, ssh keys, pem files) never enter the model context.
+- Destructive shell commands are refused.
+- Everything is jailed to your working directory.
+- Plan mode lets you preview intent before any change.
 
-</div>
+## Works with any provider
+
+OpenAI, iNeed API, OmniRoute, LM Studio, Ollama, vLLM, Groq, Together, OpenRouter, or anything that speaks the OpenAI format. You bring the key, ineed brings the agent.
+
+## For beginners, by a beginner's journey
+
+This project exists so anyone can start vibecoding: describe what you want, watch the agent work, learn from what it does. Free tutorials and AI resources live at [ineed.web.id](https://ineed.web.id), the product home is [ineed.codes](https://ineed.codes).
+
+## Contributing
+
+Issues and PRs are welcome at [github.com/ineedcodes/ineedcodes](https://github.com/ineedcodes/ineedcodes).
+
+## License
+
+[MIT](LICENSE) - 0xyas

package/package.json

@@ -1,18 +1,35 @@
 {
   "name": "ineedcodes",
-  "version": "0.2.0",
-  "description": "ineed: your terminal, now autonomous. Minimal, self-contained AI agent.",
+  "version": "1.0.0",
+  "description": "Your terminal, now autonomous. Just say what you want, ineed does the rest.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "ineed": "agent.mjs"
+    "ineed": "src/cli.js"
   },
-  "scripts": {},
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
+  "scripts": {
+    "test": "node test/smoke.mjs && node test/pack.mjs"
+  },
+  "author": {
+    "name": "0xyas",
+    "email": "arkhanalghozali18@gmail.com",
+    "url": "https://ineed.codes"
+  },
+  "homepage": "https://ineed.codes",
   "repository": {
-    "type": "git"
+    "type": "git",
+    "url": "git+https://github.com/ineedcodes/ineedcodes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ineedcodes/ineedcodes/issues"
   },
   "keywords": [
     "ai",
@@ -21,16 +38,8 @@
     "terminal",
     "autonomous",
     "coding",
-    "llm"
-  ],
-  "devDependencies": {
-    "@types/node": "^22.10.2",
-    "esbuild": "^0.28.2",
-    "typescript": "^5.6.3"
-  },
-  "files": [
-    "agent.mjs",
-    "README.md",
-    "LICENSE"
+    "vibecoding",
+    "llm",
+    "openai-compatible"
   ]
 }

package/src/agent.js

@@ -0,0 +1,106 @@
+// agent.js: the loop. objective -> reason -> tool call -> observe real result -> repeat -> verify -> report.
+
+import { chat } from './provider.js';
+import { TOOLS, runTool, shellRun, isDestructive } from './tools.js';
+import { trunc, gray, cyan, dim } from './ui.js';
+
+export const MAX_STEPS = 30;
+export const MAX_HISTORY_CHARS = 30_000;
+export const MAX_TURNS = 40;
+
+const SYSTEM = `You are ineed, an autonomous terminal agent on the user's machine.
+Rules:
+- Use the tools to do real work. Never invent output. Every success claim needs evidence from a tool result.
+- Prefer targeted edits (edit_file) over full rewrites (write_file). Work only inside the current folder.
+- Never push to remotes or delete data without being asked.
+- Destructive commands are blocked. Ask the user to run those themselves.
+- When the objective is done, verify it (run the tests, read the file back, whatever proves it), then reply with the final result in this shape:
+  What changed, what you ran, the evidence you saw.`;
+
+export function trimHistory(history) {
+  let start = history.length, total = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    total += (history[i].content?.length ?? 0) + 24;
+    if (total > MAX_HISTORY_CHARS) break;
+    start = i;
+  }
+  return history.slice(start);
+}
+
+export async function runObjective(cfg, objective, cwd, history, hooks = {}) {
+  const ctrl = new AbortController();
+  hooks.onRunStart?.(ctrl);
+  const plan = cfg.mode === 'plan';
+  const tools = plan ? TOOLS.filter(t => t.allowedInPlan) : TOOLS;
+  const messages = [
+    {
+      role: 'system',
+      content: `${SYSTEM}\nWorking directory: ${cwd}\nMode: ${plan ? 'plan (read only, suggest what to change, do not change anything)' : 'build'}`
+    },
+    ...trimHistory(history),
+    { role: 'user', content: objective }
+  ];
+  const changed = new Set();
+  const ran = [];
+  let answer = '';
+  let lastShown = '';
+  try {
+    for (let step = 0; step < MAX_STEPS; step++) {
+      if (ctrl.signal.aborted) break;
+      let msg;
+      try {
+        msg = await chat(cfg, messages, tools, ctrl.signal);
+      } catch (err) {
+        if (ctrl.signal.aborted) break;
+        throw err;
+      }
+      messages.push(msg);
+      if (msg.content && msg.content !== lastShown) {
+        hooks.onText?.(msg.content);
+        lastShown = msg.content;
+        answer = msg.content;
+      }
+      const calls = msg.tool_calls ?? [];
+      if (calls.length === 0) {
+        return { answer, changed: [...changed], ran, aborted: false };
+      }
+      for (const call of calls) {
+        let input = {};
+        try { input = JSON.parse(call.function?.arguments || '{}'); } catch {}
+        hooks.onTool?.(call.function?.name, input);
+        let result;
+        if (call.function?.name === 'shell') {
+          if (plan) result = { output: 'Refused: plan mode is read only. Switch to build mode with /build.' };
+          else if (isDestructive(String(input.command ?? ''))) {
+            result = { output: 'Refused: that command is destructive. Run it yourself if you are sure.' };
+          } else {
+            result = await shellRun(String(input.command ?? ''), cwd, ctrl.signal);
+            ran.push(String(input.command ?? '').slice(0, 120));
+          }
+        } else {
+          if (plan && !TOOLS.find(t => t.name === call.function?.name)?.allowedInPlan) {
+            result = { output: 'Refused: plan mode is read only. Switch to build mode with /build.' };
+          } else {
+            result = runTool(call.function?.name, input, cwd);
+            if (!plan && ['write_file', 'edit_file', 'delete_file'].includes(call.function?.name)
+              && !/^(Refused|Error)/.test(String(result.output))) {
+              changed.add(String(input.path ?? ''));
+            }
+          }
+        }
+        hooks.onResult?.(result.output);
+        messages.push({ role: 'tool', tool_call_id: call.id, content: String(result.output).slice(0, 20_000) });
+      }
+    }
+  } finally {
+    hooks.onRunEnd?.();
+  }
+  const stopped = ctrl.signal.aborted;
+  return { answer, changed: [...changed], ran, aborted: true, stopped };
+}
+
+export function pushTurn(history, objective, result) {
+  history.push({ role: 'user', content: objective }, { role: 'assistant', content: result.answer });
+  if (history.length > MAX_TURNS * 2) history = history.slice(-MAX_TURNS * 2);
+  return history;
+}

package/src/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// ineed: your terminal, now autonomous.
+// First open asks for provider setup. After that, just say what you want.
+
+import * as fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const [MAJOR] = process.versions.node.split('.').map(Number);
+if (!(MAJOR >= 20)) {
+  console.error(`ineed needs Node.js 20 or newer. You have ${process.versions.node}.`);
+  console.error('Install a newer Node from https://nodejs.org and try again.');
+  process.exit(1);
+}
+
+const { loadConfig } = await import('./config.js');
+const { VERSION, bold, dim, red, green, yellow } = await import('./ui.js');
+
+const args = process.argv.slice(2);
+
+if (args[0] === '--version' || args[0] === '-v') {
+  console.log(`ineed ${VERSION}`);
+  process.exit(0);
+}
+
+if (args[0] === '--help' || args[0] === '-h') {
+  console.log(`
+${bold('ineed')} ${dim(`v${VERSION}`)} - your terminal, now autonomous
+
+  ${green('ineed')}                        interactive session (first open: setup)
+  ${green('ineed "fix the build errors"')}  one-shot task
+  ${green('ineed --reset')}                 redo provider setup
+  ${green('ineed --version')}               show version
+
+Inside a session, ${dim('/help')} lists the shortcuts. Or just talk to it.
+`);
+  process.exit(0);
+}
+
+// internal: one-shot worker. Spawned by the branch below, never run by users.
+if (args[0] === '--child') {
+  const task = args.slice(1).join(' ');
+  const { runObjective } = await import('./agent.js');
+  const cfg = loadConfig();
+  if (!cfg) {
+    console.error(red('No provider configured. Run ') + bold('ineed') + red(' first to set one up.'));
+    process.exit(1);
+  }
+  try {
+    const res = await runObjective(cfg, task, process.cwd(), []);
+    if (res.aborted) {
+      console.log('\n' + yellow('Stopped.') + dim(' Task did not finish (step limit or Ctrl+C). Re-run to continue.'));
+      process.exit(2);
+    }
+    console.log('\n' + bold(green('Done')) + (res.changed?.length ? dim('  changed: ' + res.changed.join(', ')) : ''));
+    if (res.answer) console.log('  ' + res.answer.split('\n').slice(0, 14).join('\n  '));
+    process.exit(0);
+  } catch (err) {
+    console.error(red('Error: ' + err.message));
+    process.exit(1);
+  }
+}
+
+// one-shot task: keep this process alive as the parent, run the worker as a child
+if (args.length > 0 && args[0] !== '--reset') {
+  const child = spawn(process.execPath, [new URL(import.meta.url).pathname, '--child', ...args], { stdio: 'inherit' });
+  child.on('exit', code => process.exit(code ?? 1));
+} else {
+  // interactive session or setup
+  const readline = await import('node:readline');
+  const { makeInput } = await import('./ui.js');
+  const { wizard } = await import('./wizard.js');
+  const { startSession } = await import('./session.js');
+  const { clearConfig } = await import('./config.js');
+
+  if (args[0] === '--reset') {
+    clearConfig();
+    console.log(dim('Setup cleared. Let\'s set it up again.'));
+  }
+
+  let cfg = loadConfig();
+  if (!cfg) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = makeInput(rl);
+    try {
+      cfg = await wizard(ask);
+    } catch (err) {
+      if (err.aborted) { console.log(dim('\nSetup aborted. Run `ineed` to try again.')); process.exit(1); }
+      throw err;
+    }
+    rl.close();
+  }
+  await startSession(cfg);
+}

package/src/config.js

@@ -0,0 +1,39 @@
+// config.js: load, validate, save provider config. Secrets never get printed here.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export const CONFIG_DIR = process.env.INEED_CONFIG_DIR || path.join(os.homedir(), '.ineedcodes');
+export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export function loadConfig() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    if (c && typeof c.baseUrl === 'string' && typeof c.apiKey === 'string' && typeof c.model === 'string'
+      && c.baseUrl && c.model) return normalize(c);
+  } catch {}
+  return null;
+}
+
+export function normalize(c) {
+  return {
+    baseUrl: String(c.baseUrl).replace(/\/+$/, ''),
+    apiKey: String(c.apiKey ?? ''),
+    model: String(c.model),
+    reasoning: c.reasoning === 'high' ? 'high' : 'low',
+    mode: c.mode === 'plan' ? 'plan' : 'build'
+  };
+}
+
+export function saveConfig(c) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const clean = normalize(c);
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(clean, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch {}
+  return clean;
+}
+
+export function clearConfig() {
+  try { fs.unlinkSync(CONFIG_FILE); } catch {}
+}

package/src/provider.js

@@ -0,0 +1,59 @@
+// provider.js: OpenAI-compatible chat + model listing. Timeout and cancellation built in.
+
+const HTTP_TIMEOUT = 120_000;
+
+async function request(url, opts, signal) {
+  const ctrl = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; ctrl.abort(); }, HTTP_TIMEOUT);
+  const relay = () => ctrl.abort();
+  signal?.addEventListener('abort', relay, { once: true });
+  try {
+    return await fetch(url, { ...opts, signal: ctrl.signal });
+  } catch (err) {
+    if (signal?.aborted) { const e = new Error('stopped by user'); e.stopped = true; throw e; }
+    if (timedOut) throw new Error('request timed out after 120s');
+    throw new Error(`cannot reach ${url}: ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', relay);
+  }
+}
+
+export async function fetchModels(cfg, signal) {
+  const headers = { accept: 'application/json' };
+  if (cfg.apiKey) headers.authorization = `Bearer ${cfg.apiKey}`;
+  const res = await request(`${cfg.baseUrl}/models`, { headers }, signal);
+  if (!res.ok) throw new Error(`HTTP ${res.status} on GET /models`);
+  const data = await res.json();
+  const ids = (data.data ?? []).map(m => m.id).filter(Boolean);
+  return [...new Set(ids)];
+}
+
+export async function chat(cfg, messages, tools, signal) {
+  const body = { model: cfg.model, messages, temperature: 0.2 };
+  if (cfg.reasoning === 'high') body.reasoning_effort = 'high';
+  if (tools?.length) body.tools = tools.map(t => ({
+    type: 'function',
+    function: { name: t.name, description: t.description, parameters: t.parameters }
+  }));
+  const headers = { 'content-type': 'application/json' };
+  if (cfg.apiKey) headers.authorization = `Bearer ${cfg.apiKey}`;
+  const res = await request(`${cfg.baseUrl}/chat/completions`, { method: 'POST', headers, body: JSON.stringify(body) }, signal);
+  if (!res.ok) {
+    const text = await res.text();
+    // provider does not know reasoning_effort: retry once without it
+    if (body.reasoning_effort && (res.status === 400 || res.status === 422)) {
+      delete body.reasoning_effort;
+      const retry = await request(`${cfg.baseUrl}/chat/completions`, { method: 'POST', headers, body: JSON.stringify(body) }, signal);
+      if (!retry.ok) throw new Error(`HTTP ${retry.status}: ${(await retry.text()).slice(0, 200)}`);
+      return parseMessage(await retry.json());
+    }
+    throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
+  }
+  return parseMessage(await res.json());
+}
+
+function parseMessage(json) {
+  return json.choices?.[0]?.message ?? { role: 'assistant', content: '', tool_calls: [] };
+}