@rxpm/forge-cli 0.0.1

package/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.env
+.git
+.DS_Store
+package-lock.json

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+    "tabWidth": 4,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "all",
+    "printWidth": 180,
+    "bracketSameLine": true,
+    "bracketSpacing": true
+}

package/AGENT_RULES.md

@@ -0,0 +1,42 @@
+## Execution Discipline
+
+1. Always read before writing
+2. Never assume context
+3. Break tasks into steps
+4. Validate after every change
+
+---
+
+## Tool Usage Policy
+
+* Prefer read_file before any modification
+* Use search before scanning entire repo
+* Use small edits instead of full rewrites
+
+---
+
+## Failure Recovery
+
+If stuck:
+
+1. Re-evaluate plan
+2. Re-read relevant files
+3. Try alternative approach
+
+---
+
+## Coding Standards
+
+* Follow existing code style
+* Do not introduce new frameworks
+* Keep changes minimal and reversible
+
+---
+
+## Communication
+
+* Be direct
+* No verbose explanations
+* Focus on actions
+
+---

package/Dockerfile

@@ -0,0 +1,32 @@
+# Use Node.js 22 as the base image
+FROM node:22-slim
+
+# Install git and grep (required by tools)
+RUN apt-get update && apt-get install -y git grep && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy the rest of the source code
+COPY . .
+
+# Build the TypeScript project
+RUN npm run build
+
+# Make the binary executable
+RUN chmod +x dist/index.js
+
+# Link the package so 'forge' is available globally in the container
+RUN npm link
+
+# Set the working directory to /workspace for user projects
+WORKDIR /workspace
+
+# Default entrypoint
+ENTRYPOINT ["forge"]

package/README.md

@@ -0,0 +1,117 @@
+<!--
+File: README.md
+Author: Rajat Sharma
+Date: 2026-03-26
+-->
+
+# Forge Coding Agent
+
+A terminal-based AI coding agent built with Node.js, TypeScript, and the Vercel AI SDK. This agent can read, modify, and generate code in your local repository using LLMs via Ollama.
+
+![Preview](./assets/preview_explain.webp)
+
+## Prerequisites
+
+- **Node.js**: >= 18.x
+- **Ollama**: A running Ollama instance (local or cloud).
+
+## Installation
+
+1. **Clone the repository**:
+
+```bash
+git clone <repository-url>
+cd forge
+```
+
+2. **Install dependencies**:
+
+```bash
+npm install
+```
+
+3. **Configure Environment**:
+
+Create a `.env` file in the root directory:
+
+```env
+OLLAMA_API_URL="https://your-ollama-endpoint"
+OLLAMA_API_KEY="your-api-key-if-needed"
+```
+
+4. **Build the project**:
+
+```bash
+npm run build
+```
+
+5. **Link the CLI (Optional)**:
+
+To use the `agent` command globally:
+
+```bash
+npm link
+```
+
+## Usage
+
+### Run a Task
+
+Execute a specific coding task:
+
+```bash
+forge "Add a new endpoint to src/server.ts that returns system health"
+```
+
+### Explain Code
+
+Get an explanation for a specific file:
+
+```bash
+forge explain src/agent/loop.ts
+```
+
+### Fix Errors
+
+Automatically detect and attempt to fix errors in the project:
+
+```bash
+forge fix
+```
+
+### Interactive Chat
+
+Start an interactive session (currently executes as a single multi-step task):
+
+```bash
+forge chat
+```
+
+### Docker Usage
+
+You can run the agent as a Docker container to avoid local Node.js environment setup.
+
+1. **Build the image**:
+
+```bash
+docker build -t forge-agent .
+```
+
+2. **Run the agent** (mount your project as `/workspace`):
+
+```bash
+docker run -it --rm \
+   -v $(pwd):/workspace \
+   --env-file .env \
+   forge-agent "List files in the workspace"
+```
+
+Note: Ensure your `.env` file contains the correct `OLLAMA_API_URL` accessible from inside the container.
+
+## License
+
+ISC
+
+## Author
+
+Rajat Sharma (rajatxt@proton.me)

package/REQUIREMENTS.md

@@ -0,0 +1,233 @@
+## 1. Objective
+
+Build a terminal-based AI coding agent (CLI tool) capable of reading, modifying, and generating code across a local repository using an open-source LLM via Ollama.
+
+The agent must behave similarly to Claude Code:
+
+* Understand user intent
+* Explore codebase
+* Plan changes
+* Execute edits
+* Iterate until task completion
+
+---
+
+## 2. Core Principles
+
+1. Deterministic over clever
+2. Small, verifiable steps
+3. Tool-driven execution (no hallucinated actions)
+4. Always validate before proceeding
+5. Prefer editing existing files over creating new ones
+
+---
+
+## 3. Tech Stack
+
+* Runtime: Node.js (>=18)
+* Language: TypeScript
+* CLI: commander (or yargs)
+* UI (optional): ink
+* LLM: Ollama (OpenAI-compatible API)
+* SDK: Vercel AI SDK (`ai`)
+* Validation: zod
+
+---
+
+## 4. High-Level Architecture
+
+CLI Input
+→ Agent Loop
+→ LLM (Ollama)
+→ Tool Calls
+→ Execution Layer
+→ Updated Context
+→ Repeat
+
+---
+
+## 5. Required Features
+
+### 5.1 CLI Commands
+
+* `agent "<task>"` → execute coding task
+* `agent chat` → interactive mode
+* `agent explain <file>` → explain code
+* `agent fix` → detect and fix errors
+
+---
+
+### 5.2 Agent Loop
+
+The agent MUST follow this loop:
+
+1. Read current context
+2. Ask LLM for next step
+3. If tool call:
+
+   * Execute tool
+   * Append result to context
+4. If final answer:
+
+   * Output to user
+   * Exit loop
+
+Loop must have:
+
+* max iterations limit (default: 10)
+* timeout protection
+* retry mechanism (on invalid tool call)
+
+---
+
+### 5.3 Tool System
+
+All actions MUST go through tools.
+
+#### Required Tools
+
+##### File System
+
+* read_file(path)
+* write_file(path, content)
+* list_files(path)
+
+##### Codebase Navigation
+
+* search_code(query)
+* open_file_lines(path, start, end)
+
+##### Shell
+
+* run_command(cmd)
+
+##### Git (optional but recommended)
+
+* git_status()
+* git_diff()
+* git_commit(message)
+
+---
+
+### 5.4 Tool Rules
+
+* NEVER assume file contents without reading
+* NEVER overwrite files without justification
+* ALWAYS show diffs before major rewrites
+* LIMIT file size (max 5000 lines per read)
+
+---
+
+## 6. Prompting Strategy
+
+System prompt MUST enforce:
+
+* You are a coding agent operating in a real filesystem
+* You must use tools to interact with environment
+* Do not hallucinate file contents
+* Prefer minimal changes
+* Always verify results
+
+---
+
+## 7. Context Management
+
+* Maintain conversation history
+* Include:
+
+  * user request
+  * tool outputs
+  * recent file contents
+* Trim context when too large
+
+---
+
+## 8. Streaming
+
+* Stream LLM responses to terminal
+* Show tool usage clearly
+* Indicate current step (e.g. "Reading file...", "Applying patch...")
+
+---
+
+## 9. Error Handling
+
+Must handle:
+
+* invalid tool calls
+* missing files
+* command failures
+* LLM malformed output
+
+On error:
+
+* retry once with correction
+* otherwise surface error clearly
+
+---
+
+## 10. Safety Constraints
+
+* Do not run destructive commands without confirmation
+* Do not modify system files outside project root
+* Do not execute arbitrary shell commands without validation
+
+---
+
+## 11. Configuration
+
+Support:
+
+* model selection (default: llama3)
+* max iterations
+* temperature (optional)
+* root directory
+
+---
+
+## 12. Output Behavior
+
+* Be concise
+* Show actions taken
+* Show diffs for edits
+* Avoid unnecessary explanations
+
+---
+
+## 13. Project Structure
+
+/src
+/cli
+/agent
+/tools
+/llm
+/utils
+
+---
+
+## 14. Definition of Done
+
+Task is complete when:
+
+* requested changes are implemented
+* code compiles / runs (if applicable)
+* no pending errors detected
+
+---
+
+## 15. Non-Goals
+
+* No GUI
+* No cloud dependency
+* No long-term memory (v1)
+
+---
+
+## 16. Future Enhancements (Optional)
+
+* multi-agent planning
+* test generation
+* auto-debug loop
+* IDE integration
+
+---

package/dist/agent/loop.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs the AI agent to solve the given task.
+ * @param task The task to solve.
+ * @param maxIterations The maximum number of iterations to run the agent for.
+ */
+export declare function runAgent(task: string, maxIterations?: number): Promise<void>;

package/dist/agent/loop.js

@@ -0,0 +1,62 @@
+import { stepCountIs, ToolLoopAgent } from 'ai';
+import { ollama, defaultModel } from '../llm/provider.js';
+import { tools } from '../tools/index.js';
+import { ActivityDisplay } from '../ui/activity.js';
+const SYSTEM_PROMPT = `
+You are a senior AI coding agent operating in a real filesystem.
+Your goal is to solve the user's coding task by following a logical process:
+1. Explore the codebase to understand the current state.
+2. Plan your changes carefully.
+3. Execute the changes by writing complete, valid files or code blocks.
+4. Verify your work using the tools provided.
+
+## Core Rules:
+1. ALWAYS read a file before modifying it.
+2. NEVER guess file content.
+3. When writing a file, PROVIDE THE FULL CONTENT of the file unless instructed otherwise.
+4. Use small, verifiable steps.
+5. If a command fails, analyze the error and try a different approach.
+6. Be concise and professional. No fluff.
+
+## Tools Available:
+- read_file(path): Returns the full content of a file.
+- write_file(path, content): Writes the EXACT content to a file.
+- list_files(path): Lists all files in the given directory.
+- search_code(query): Searches for a string in the codebase.
+- open_file_lines(path, start, end): Reads specific lines (1-indexed).
+- run_command(cmd): Executes a shell command.
+- git_status(), git_diff(), git_commit(message): Git operations.
+
+Always verify your changes after writing.
+`;
+/**
+ * Runs the AI agent to solve the given task.
+ * @param task The task to solve.
+ * @param maxIterations The maximum number of iterations to run the agent for.
+ */
+export async function runAgent(task, maxIterations = 10) {
+    const display = new ActivityDisplay();
+    try {
+        // Show branded banner
+        ActivityDisplay.printBanner(task);
+        // Start thinking indicator
+        display.startThinking();
+        const agent = new ToolLoopAgent({
+            model: ollama(defaultModel),
+            instructions: SYSTEM_PROMPT,
+            tools,
+            maxRetries: 2,
+            toolChoice: 'required',
+            stopWhen: stepCountIs(maxIterations),
+            onStepFinish(step) {
+                display.onStepFinish(step);
+            },
+        });
+        await agent.generate({ prompt: task });
+        display.printSummary('success');
+    }
+    catch (error) {
+        display.printSummary('error', error.message);
+    }
+}
+//# sourceMappingURL=loop.js.map

package/dist/agent/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,aAAa,GAAG,EAAE;IAC3D,MAAM,OAAO,GAAG,IAAI,eAAe,EAAE,CAAC;IAEtC,IAAI,CAAC;QACD,sBAAsB;QACtB,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAElC,2BAA2B;QAC3B,OAAO,CAAC,aAAa,EAAE,CAAC;QAExB,MAAM,KAAK,GAAG,IAAI,aAAa,CAAC;YAC5B,KAAK,EAAE,MAAM,CAAC,YAAY,CAAC;YAC3B,YAAY,EAAE,aAAa;YAC3B,KAAK;YACL,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,UAAU;YACtB,QAAQ,EAAE,WAAW,CAAC,aAAa,CAAC;YACpC,YAAY,CAAC,IAAI;gBACb,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;SACJ,CAAC,CAAC;QAEH,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAEvC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QAClB,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;AACL,CAAC"}

package/dist/cli/commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+declare const program: Command;
+export { program };

package/dist/cli/commands.js

@@ -0,0 +1,40 @@
+import { Command } from 'commander';
+import { runAgent } from '../agent/loop.js';
+import { logger } from '../utils/logger.js';
+const program = new Command();
+program
+    .name('forge')
+    .description('AI coding agent CLI tool')
+    .version('0.0.1')
+    .argument('[task]', 'The task to execute (default if no command provided)')
+    .option('-i, --iterations <number>', 'Maximum number of iterations', '10')
+    .action(async function (task, options) {
+    if (task) {
+        await runAgent(task, parseInt(options.iterations));
+    }
+    else {
+        program.help();
+    }
+});
+program
+    .command('chat')
+    .description('Interactive mode (v1: executes a single multi-step task)')
+    .action(async function () {
+    logger.warn('Interactive chat mode is currently limited to executing single tasks via main "agent <task>" command.');
+});
+program
+    .command('explain')
+    .argument('<file>', 'The file to explain')
+    .action(async function (file) {
+    const task = `Explain the code in the file: ${file}`;
+    await runAgent(task);
+});
+program
+    .command('fix')
+    .description('Detect and fix errors in the project')
+    .action(async function () {
+    const task = `Search for errors in the project, check git status, and try to fix any obvious bugs.`;
+    await runAgent(task);
+});
+export { program };
+//# sourceMappingURL=commands.js.map

package/dist/cli/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,0BAA0B,CAAC;KACvC,OAAO,CAAC,OAAO,CAAC;KAChB,QAAQ,CAAC,QAAQ,EAAE,sDAAsD,CAAC;KAC1E,MAAM,CAAC,2BAA2B,EAAE,8BAA8B,EAAE,IAAI,CAAC;KACzE,MAAM,CAAC,KAAK,WAAW,IAAI,EAAE,OAAO;IACjC,IAAI,IAAI,EAAE,CAAC;QACP,MAAM,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACJ,OAAO,CAAC,IAAI,EAAE,CAAC;IACnB,CAAC;AACL,CAAC,CAAC,CAAC;AAEP,OAAO;KACF,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,0DAA0D,CAAC;KACvE,MAAM,CAAC,KAAK;IACT,MAAM,CAAC,IAAI,CAAC,uGAAuG,CAAC,CAAC;AACzH,CAAC,CAAC,CAAC;AAEP,OAAO;KACF,OAAO,CAAC,SAAS,CAAC;KAClB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;KACzC,MAAM,CAAC,KAAK,WAAW,IAAI;IACxB,MAAM,IAAI,GAAG,iCAAiC,IAAI,EAAE,CAAC;IACrD,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC;AAEP,OAAO;KACF,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,sCAAsC,CAAC;KACnD,MAAM,CAAC,KAAK;IACT,MAAM,IAAI,GAAG,sFAAsF,CAAC;IACpG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC;AAEP,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    /** Get the API URL for the Ollama server. */
+    readonly ollamaApiUrl: string;
+    /** Get the API secret for the Ollama server. */
+    readonly ollamaApiSecret: string;
+    /** Get the default model to use for the AI agent. */
+    readonly defaultModel: string;
+};
+export default _default;

package/dist/config/env.js

@@ -0,0 +1,16 @@
+export default {
+    /** Get the API URL for the Ollama server. */
+    get ollamaApiUrl() {
+        const baseUrl = process.env.OLLAMA_API_URL || 'http://localhost:11434';
+        return `${baseUrl}/api`;
+    },
+    /** Get the API secret for the Ollama server. */
+    get ollamaApiSecret() {
+        return process.env.OLLAMA_API_KEY || '';
+    },
+    /** Get the default model to use for the AI agent. */
+    get defaultModel() {
+        return process.env.OLLAMA_DEFAULT_MODEL || 'gpt-oss:120b';
+    },
+};
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,eAAe;IACX,6CAA6C;IAC7C,IAAI,YAAY;QACZ,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,wBAAwB,CAAC;QACvE,OAAO,GAAG,OAAO,MAAM,CAAC;IAC5B,CAAC;IAED,gDAAgD;IAChD,IAAI,eAAe;QACf,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IAC5C,CAAC;IAED,qDAAqD;IACrD,IAAI,YAAY;QACZ,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,cAAc,CAAC;IAC9D,CAAC;CACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * File: src/index.ts
+ * Author: Rajat Sharma
+ * Description: The main entry point for the CLI tool.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * File: src/index.ts
+ * Author: Rajat Sharma
+ * Description: The main entry point for the CLI tool.
+ */
+import { program } from './cli/commands.js';
+import { logger } from './utils/logger.js';
+/** The main function that parses the command line arguments and executes the corresponding command. */
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        logger.error(`CLI execution failed: ${error.message}`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,uGAAuG;AACvG,KAAK,UAAU,IAAI;IACf,IAAI,CAAC;QACD,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QAClB,MAAM,CAAC,KAAK,CAAC,yBAAyB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/llm/provider.d.ts

@@ -0,0 +1,4 @@
+/** The default model to use for the AI agent. */
+export declare const defaultModel: string;
+/** The Ollama client for the AI agent. */
+export declare const ollama: import("ollama-ai-provider-v2").OllamaProvider;

package/dist/llm/provider.js

@@ -0,0 +1,12 @@
+import { createOllama } from 'ollama-ai-provider-v2';
+import env from '../config/env.js';
+/** The default model to use for the AI agent. */
+export const defaultModel = env.defaultModel;
+/** The Ollama client for the AI agent. */
+export const ollama = createOllama({
+    baseURL: env.ollamaApiUrl + '/api',
+    headers: {
+        Authorization: `Bearer ${env.ollamaApiSecret}`,
+    },
+});
+//# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,GAAG,MAAM,kBAAkB,CAAC;AAEnC,iDAAiD;AACjD,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;AAE7C,0CAA0C;AAC1C,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAC;IAC/B,OAAO,EAAE,GAAG,CAAC,YAAY,GAAG,MAAM;IAClC,OAAO,EAAE;QACL,aAAa,EAAE,UAAU,GAAG,CAAC,eAAe,EAAE;KACjD;CACJ,CAAC,CAAC"}

package/dist/tools/code.d.ts

@@ -0,0 +1,15 @@
+/**
+ * File: code.ts
+ * Author: Rajat Sharma
+ * Description: Code tools for the AI agent.
+ */
+/** Searches for a string in the codebase using grep. */
+export declare const searchCodeTool: import("ai").Tool<{
+    query: string;
+}, string>;
+/** Opens a file and reads specific line range. */
+export declare const openFileLinesTool: import("ai").Tool<{
+    path: string;
+    start: number;
+    end: number;
+}, string>;