Skip to content

README.md

Latest commit

 

History

History
181 lines (134 loc) · 5.56 KB

README.md

File metadata and controls

181 lines (134 loc) · 5.56 KB
Raw

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 >= 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+:

# 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

Installation

# 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:

# 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:

{
  "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

# 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

# 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