# NimCode

**Repository Path**: startvibecoding/NimCode

## Basic Information

- **Project Name**: NimCode
- **Description**: NimCode is an AI coding assistant that runs in your terminal, written in pure Nim with no external dependencies.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NimCode

NimCode is an AI coding assistant that runs in your terminal, written in pure Nim with no external dependencies.

## Features

- **Pure Nim** — Uses only the Nim standard library, no external dependencies
- **Multiple providers** — Supports OpenAI Chat/Responses-compatible APIs, Anthropic Messages, Google Gemini, DeepSeek, and compatible endpoints
- **Built-in tools** — read, write, edit, bash, ls, grep, find, plan, jobs, kill, cron, spawn, skill_ref, memory_read, memory_write, a2a_dispatch, plus MCP-provided tools
- **Session persistence** — JSONL session storage with resume/list commands
- **Project context** — Automatically loads AGENTS.md, CLAUDE.md, .cursorrules, project/global skills, and persistent memory
- **Multiple modes** — plan (read-only), agent (default), yolo (unrestricted)
- **Integrations** — MCP client support, sandboxed bash execution, cron jobs, A2A/ACP protocol modules, Hermes daemon, and gateway components

## Supported Platforms

| Platform | amd64 | arm64 | Notes |
|----------|-------|-------|-------|
| Linux | ✓ | ✓ | Primary targets |
| Windows | ✓ | ○ | amd64 ready; arm64 needs cross-compiler |
| macOS | ○ | ○ | Cross-compilation requires Zig or osxcross |
| Linux (loongarch64) | ○ | — | `--cpu:loongarch64` supported by Nim 2.2+ |

## Prerequisites

### Required

- [Nim](https://nim-lang.org/) >= 2.0.0
- `gcc` (for Linux amd64 native builds)

### For cross-compilation (release builds)

The following packages provide the cross-compilers used by `./scripts/build-cross-platform.sh`:

**Debian 12 / Ubuntu 22.04+:**

```bash
# Linux amd64 (native) + arm64 (cross)
sudo apt-get install -y gcc gcc-aarch64-linux-gnu libc6-dev-arm64-cross

# Windows amd64 (cross)
sudo apt-get install -y mingw-w64

# Optional: all platforms with one tool (recommended)
# Install Zig and it will handle linux-arm64, windows-arm64, macOS, loongarch64
wget https://ziglang.org/download/0.14.0/zig-linux-x86_64-0.14.0.tar.xz
tar -xf zig-linux-x86_64-0.14.0.tar.xz
sudo mv zig-linux-x86_64-0.14.0 /opt/zig
sudo ln -s /opt/zig/zig /usr/local/bin/zig
```

**Package reference by target:**

| Target | Debian/Ubuntu Package |
|--------|----------------------|
| linux-amd64 | `gcc` (native) |
| linux-arm64 | `gcc-aarch64-linux-gnu` + `libc6-dev-arm64-cross` |
| linux-arm | `gcc-arm-linux-gnueabihf` + `libc6-dev-armhf-cross` |
| linux-loongarch64 | `gcc-loongarch64-linux-gnu` (Debian 13+/unstable) |
| windows-amd64 | `mingw-w64` |
| windows-arm64 | `mingw-w64` (>= 10.0, Debian 12+) |
| macos-amd64/arm64 | No Debian package; use **Zig** or [osxcross](https://github.com/tpoechtrager/osxcross) |

## Installation

```bash
# Clone the repository
git clone <repository-url>
cd nimcode

# Compile (native Linux amd64)
nim c -d:ssl -o:bin/nimcode src/nimcode.nim

# Or with release optimizations
nim c -d:ssl -d:release --opt:size -o:bin/nimcode src/nimcode.nim
```

## Release Build (cross-platform)

Build binaries for all supported platforms, plus `.deb` and npm packages:

```bash
# Build everything
make release

# Or individual targets
make cross-compile   # Cross-platform binaries
make package-deb     # Debian package (host arch)
make package-npm     # npm tarball (no publish)
```

Outputs are placed in `dist/`.

## Configuration

Create a configuration file at `~/.nimcode/settings.json`:

```json
{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek-chat",
  "defaultMode": "agent",
  "defaultThinkingLevel": "medium",
  "sandbox": { "enabled": false, "level": "none" },
  "webSearch": { "enabled": false, "providerType": "responses" }
}
```

Or use environment variables:
- `NIMCODE_PROVIDER` — Default provider
- `NIMCODE_MODEL` — Default model
- `OPENAI_API_KEY` — OpenAI API key
- `ANTHROPIC_API_KEY` — Anthropic API key
- `GOOGLE_API_KEY` — Google Gemini API key
- `DEEPSEEK_API_KEY` — DeepSeek API key

## Usage

```bash
# Interactive mode
./bin/nimcode

# With specific provider and model
./bin/nimcode -p deepseek -m deepseek-chat

# YOLO mode (all tools auto-execute)
./bin/nimcode -M yolo

# Print mode (non-interactive)
./bin/nimcode --print "explain this code"

# Continue most recent session
./bin/nimcode -c
```

## Built-in Tools

- **read** — Read file contents (supports text and images)
- **write** — Write content to files
- **edit** — Edit files using exact text replacement
- **bash** — Execute shell commands, including optional async background jobs and timeout control
- **ls** — List directory contents
- **grep** — Search file contents using regex
- **find** — Find files by name pattern
- **plan** — Publish a structured task plan
- **jobs** / **kill** — Inspect and stop background commands
- **cron** — Manage scheduled local tasks
- **spawn** — Run sub-agents for parallel work
- **skill_ref** — Load reference files from active skills
- **memory_read** / **memory_write** — Read and write persistent memory at `~/.nimcode/memory.md`
- **a2a_dispatch** — Send tasks to remote A2A servers
- **MCP tools** — Tools exposed by configured MCP servers are registered automatically

## Modes

- **plan** — Read-only mode. Analyze code and create plans without modifying files.
- **agent** — Default mode. Read/write files and execute commands.
- **yolo** — Unrestricted mode. All tools auto-execute without approval.

## Development

```bash
# Compile
nim c -d:ssl src/nimcode.nim

# Run one test
nim c -d:ssl -r tests/test_session.nim

# Run all current unit tests
make test

# Run thread-sensitive checks with --threads:off
make test-threads-off

# Clean test executables and local Nim test cache
make test-clean
```

## License

MIT