npm package: @radekdymacz/coder
Description: An AI coding assistant CLI powered by LangChain and Ink.
Author: Radek Dymacz
Latest version: 0.0.4

# Coder - AI Coding Assistant CLI

## Overview

`coder` is a command-line interface (CLI) tool designed as an AI coding assistant. It leverages the power of Google's Generative AI models (specifically Gemini) through the LangChain and LangGraph frameworks to provide interactive coding help and execute specific tasks.

The agent can:
*   Understand and respond to user queries in an interactive session.
*   Execute one-off commands.
*   Interact with the local file system (list directories, view files).
*   Run a limited set of safe shell commands.

## Features

*   **Interactive Mode**: Engage in a continuous conversation with the agent. Maintains history for context.
*   **One-Off Commands**: Execute single queries directly.
*   **Tool Usage**: Equipped with tools to:
    *   `list_directory`: List contents of a directory.
    *   `view_file`: View the content of a file (or specific lines).
    *   `run_command`: Execute basic, safe shell commands.
    *   `write_to_file`: Create new files with specified content.
    *   `find_by_name`: Recursively find files/directories matching a pattern.
    *   `grep_search`: Search for text patterns within files (uses `ripgrep` if available).

## Requirements

- **Node.js**: Version 18 or higher.
- **npm**: Included with Node.js.
- **ripgrep (`rg`)** (Recommended for `grep_search` tool): While the `grep_search` tool includes a basic fallback to the standard `grep` command, it performs significantly better (speed, respecting `.gitignore`, etc.) if `ripgrep` is installed and available in your system's PATH.

  **Installation:**
  - **macOS (using Homebrew):**
    ```bash
    brew install ripgrep
    ```
  - **Debian/Ubuntu (using apt):**
    ```bash
    sudo apt update
    sudo apt install ripgrep
    ```
  - **Fedora/CentOS/RHEL (using yum/dnf):**
    ```bash
    sudo yum install ripgrep # Older systems
    # or
    sudo dnf install ripgrep # Newer systems
    ```
  - **Other platforms:** See the [ripgrep repository](https://github.com/BurntSushi/ripgrep#installation) for more options (Windows, source builds, etc.).

## Technology Stack

*   Node.js & TypeScript
*   LangChain & LangGraph
*   Google Generative AI (Gemini)
*   Commander.js (for CLI)
*   Ink & React (for interactive UI)
*   Zod (for schema validation)

## Setup

1.  Clone the repository.
2.  Install dependencies:
    ```bash
    npm install
    ```
3.  Create a `.env` file in the root directory and add your Google API key:
    ```
    GOOGLE_API_KEY=YOUR_API_KEY_HERE
    ```
4.  Build the project:
    ```bash
    npm run build
    ```

## Usage

### Interactive Mode (Default)

Start a continuous chat session with the agent:

```bash
node dist/cli.js
```
or
```bash
./dist/cli.js interactive
```

Inside the session, type your requests. Use `exit` or `quit` to end.

### One-Off Command

Run a single query and get a response:

```bash
node dist/cli.js run "<your query here>"
```
Example:
```bash
node dist/cli.js run "list files in the src directory"
```

## Publishing to npm (for Maintainers)

1.  **Update `package.json`:**
    *   Ensure the `name` is correctly scoped (e.g., `@your-npm-username/coder`).
    *   Increment the `version` number according to [SemVer](https://semver.org/).
    *   Verify the `bin` field points the command name (`coder`) to the correct compiled entry point (`dist/cli.js`).
    *   Ensure the `files` array includes `dist`, `README.md`, `package.json`, and any other necessary assets.
    *   Update `description`, `keywords`, `author`, `license`, etc. as needed.
2.  **Build:** Compile the TypeScript code:
    ```bash
    npm run build
    ```
3.  **Login to npm:** Authenticate with your npm account:
    ```bash
    npm login
    ```
4.  **Publish:** Publish the package publicly:
    ```bash
    # Use --access public for scoped packages (@username/package)
    npm publish --access public
    ```

## TODO

*   [ ] **Add More Tools (Prioritized based on Cascade):**
    *   **High Priority (Core Functionality):**
        *   [ ] `edit_file`: Modify existing files based on instructions.
    *   **Medium Priority (Enhanced Capabilities):**
        *   [ ] `read_url_content`: Fetch content from a URL.
        *   [ ] `search_web`: Perform web searches via an external API.
        *   [ ] `view_code_item`: View specific code structures (functions/classes).
        *   [ ] Enhance `view_file`: Add line ranges and summaries.
        *   [ ] Enhance `run_command`: Add non-blocking options with status checks.
    *   **Lower Priority / Future Enhancements:**
        *   [ ] `create_memory`: Implement persistent memory for context across sessions.
        *   [ ] `codebase_search`: Semantic code search (requires embeddings).
*   [ ] Implement more robust error handling in tools and agent flow.
*   [ ] Add unit and integration tests.
*   [ ] Improve the safety checks for the `run_command` tool.
*   [ ] Add configuration options (e.g., model selection, temperature).
*   [ ] Enhance the agent's system prompt for better context awareness.
*   [ ] Add detailed documentation for each tool.