Skip to content
BranchesTags

Repository files navigation

 ███╗   ██╗███████╗ █████╗ ███╗   ███╗ ██████╗ ██████╗ ██████╗ ███████╗
 ████╗  ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔═══██╗██╔══██╗██╔════╝
 ██╔██╗ ██║█████╗  ███████║██╔████╔██║██║     ██║   ██║██║  ██║█████╗
 ██║╚██╗██║██╔══╝  ██╔══██║██║╚██╔╝██║██║     ██║   ██║██║  ██║██╔══╝
 ██║ ╚████║███████╗██║  ██║██║ ╚═╝ ██║╚██████╗╚██████╔╝██████╔╝███████╗
 ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
  v0.3.5

Terminal-native, multi-provider agentic AI client for the Neam ecosystem

Neam Language Latest Release License Platform Node.js TypeScript Tests Stars neam-lang

Installation • Quick Start • Features • Configuration • Development

What is NeamCode?

NeamCode is a terminal-native AI coding assistant that supports multiple LLM providers (OpenAI, Anthropic, Google Gemini, Ollama), MCP servers, agent orchestration, and the Neam compiler toolchain. Think of it as your AI pair-programmer that lives in the terminal.

Installation

Quick Install (recommended)

macOS / Linux:

curl -fsSL https://neamcode.com/install.sh | sh

Windows (PowerShell):

irm https://neamcode.com/install.ps1 | iex

npm Global Install

npm install -g neamcode

Manual Download

Download the platform-specific package from GitHub Releases:

Platform Architecture Package
macOS Apple Silicon (arm64) neamcode-v0.3.5-macos-arm64.tar.gz
macOS Intel (x86_64) neamcode-v0.3.5-macos-x64.tar.gz
Linux x86_64 neamcode-v0.3.5-linux-x64.tar.gz
Linux arm64 neamcode-v0.3.5-linux-arm64.tar.gz
Windows x86_64 neamcode-v0.3.5-windows-x64.zip

Then extract and run the installer:

# macOS / Linux
tar xzf neamcode-v0.3.5-<platform>-<arch>.tar.gz
cd neamcode-v0.3.5-<platform>-<arch>
./install.sh

# Windows — extract zip, then run in PowerShell:
.\install.ps1

Install Specific Version

curl -fsSL https://neamcode.com/install.sh | sh -s -- --version v0.3.5

Verify Download

sha256sum -c checksums.sha256

Prerequisites

The installer checks these automatically. Run install.sh --check to validate without installing.

Requirement Minimum Version
Node.js 18.0.0
npm 9.0.0
git 2.30.0
Disk space 200 MB

macOS extras: Xcode Command Line Tools, Rosetta 2 (for x86_64 on arm64)

Linux extras: glibc >= 2.31 (warn on musl/Alpine), curl, tar

Windows extras: PowerShell 5.1+, Visual C++ Redistributable

Check Prerequisites Only

curl -fsSL https://neamcode.com/install.sh | sh -s -- --check

Quick Start

# Start interactive session
neamcode

# Run a single prompt
neamcode chat --prompt "Explain async/await in TypeScript"

# Check system health
neamcode doctor

# Configure API keys
neamcode setup

# Show all commands
neamcode --help

Features

Core

  • Multi-provider LLM support — OpenAI, Anthropic, Google Gemini, Ollama (local)
  • Interactive terminal UI — Ink-based rich rendering with markdown support
  • MCP integration — Connect to Model Context Protocol servers for tools/resources
  • Agent orchestration — Multi-agent workflows with skill routing
  • Token budget tracking — Session-level cost management with warning gates
  • Neam compiler integration — Compile and run .neam files directly
  • Configurable routing — Smart/fast/local provider selection based on task
  • Slash commands — /help, /theme, /doctor, /models, /cost, and more
  • Cross-platform — macOS (arm64 + x64), Linux (x64 + arm64), Windows (x64)

v0.3.5 — Memory System Upgrade

  • Auto Memory — Persistent MEMORY.md with 200-line cap, topic file overflow, and per-project isolation
  • 6-Tier Context Hierarchy — NEAMCODE.md loaded from managed → global → ancestor → project → local → config
  • @path Import Syntax — Inline file expansion in context files with cycle detection and depth limits
  • Rules Engine — .neamcode/rules/*.md with YAML frontmatter paths: for path-scoped rules
  • Compaction Resilience — System prompt rebuilt seamlessly after context window compaction
  • JSON Migration — Legacy auto.json memories auto-converted to Markdown format

v0.3.4 — Offline Auto-Recovery

  • Ollama fallback — Automatic failover to local models when cloud providers are unreachable
  • Health monitoring — Continuous provider health checks with auto-reconnect

Configuration

NeamCode uses YAML configuration. Initialize with:

neamcode init

This creates neamcode.config.yml with sections for:

  • providers — LLM endpoints, models, and routing hints
  • tokens — Session budget and warning thresholds
  • mesh — Neam Agent Mesh gateway for registration and task routing
  • policies — Guardrails for internet access, tool use, and modality defaults

See neamcode.example.yml for a full template.

Environment Variables

Variable Description
OPENAI_API_KEY OpenAI provider API key
ANTHROPIC_API_KEY Anthropic provider API key
GEMINI_API_KEY Google Gemini API key
OLLAMA_HOST Ollama server URL (default: http://localhost:11434)

Architecture

                    ┌─────────────────────────────────┐
                    │         Terminal UI (Ink)        │
                    └──────────────┬──────────────────┘
                                   │
                    ┌──────────────▼──────────────────┐
                    │       Orchestrator / Router      │
                    └──┬──────┬──────┬──────┬────┬────┘
                       │      │      │      │    │
                ┌──────▼┐ ┌───▼───┐ ┌▼────┐ │  ┌─▼────────┐
                │OpenAI │ │Claude │ │Gemini│ │  │  Ollama   │
                └───────┘ └───────┘ └─────┘ │  └──────────┘
                                            │
                              ┌─────────────▼─────────────┐
                              │    MCP Servers / Tools     │
                              └───────────────────────────┘

Key Modules

Module Path Description
Orchestrator src/core/orchestrator.ts Main agent loop, tool dispatch, compaction
Startup src/core/startup.ts Parallel initialization of 6 subsystems
Context Builder src/core/context-builder.ts Assembles system prompt from all sources
Context Loader src/context/loader.ts 6-tier NEAMCODE.md hierarchy
Import Resolver src/context/import-resolver.ts @path inline expansion
Rules Loader src/context/rules-loader.ts Path-scoped rules engine
Auto Memory Reader src/memory/auto-reader.ts MEMORY.md loader at startup
Auto Memory Writer src/memory/auto-writer.ts LLM-based knowledge extraction at shutdown
Markdown Store src/memory/markdown-store.ts CRUD persistence with topic overflow
Providers src/providers/ LLM adapters (OpenAI, Anthropic, Gemini, Ollama)
MCP Client src/mcp/ Model Context Protocol integration
Terminal UI src/ui/ Ink-based rendering (App, MessageList, StatusBar)

Development

# Clone and install
git clone https://github.com/neam-lang/NeamCode.git
cd NeamCode
npm install

# Build
npm run build

# Run locally
node dist/index.js

# Development mode (watch)
npm run dev

# Run tests
npm test

# Lint
npm run lint

Build Outputs

File Size Description
dist/index.js ~1004 KB Main CLI bundle (tsup)
dist/ci/action-entrypoint.js ~107 KB CI action entrypoint

Test Suite

213 tests across 11 test files covering:

Area Tests Files
Memory System 49 markdown-store, auto-reader, auto-writer, project-hash, migrator
Context & Rules 21 import-resolver, rules-loader
Core 17 startup, compaction-resilience
Suggestions 6 memory-rule
Integration (E2E) 10 v035-memory-system
Existing 110 loader, providers, orchestrator, etc. 
# Run all tests
npm test

# Run specific test file
npx vitest run tests/unit/memory/markdown-store.test.ts

# Run integration tests
npm run test:integration

# Watch mode
npm run test:watch

Uninstall

# Via installer
curl -fsSL https://neamcode.com/install.sh | sh -s -- --uninstall

# Or directly
~/.neamcode/bin/neamcode uninstall

# Windows (PowerShell)
irm https://neamcode.com/install.ps1 | iex -Uninstall

User configuration in ~/.neamcode/config/ is preserved during uninstall.

Installer Options

install.sh (macOS / Linux)

Flag Description
--version <tag> Install specific version (e.g., v0.3.5)
--install-dir <path> Custom install directory (default: ~/.neamcode)
--global Install to /usr/local/bin (needs sudo)
--force Reinstall even if already present
--no-modify-path Don't modify shell RC files
--uninstall Remove NeamCode installation
--check Only run prerequisite checks
--offline <file> Install from local .tar.gz package
--yes Non-interactive mode (accept all defaults)

install.ps1 (Windows)

Parameter Description
-Version <tag> Install specific version
-InstallDir <path> Custom install directory
-Global Install system-wide (needs admin)
-Force Reinstall even if present
-NoModifyPath Don't modify User PATH
-Uninstall Remove NeamCode
-CheckOnly Only run prerequisite checks
-Offline <file> Install from local .zip package
-Yes Non-interactive mode

Directory Structure (after install)

~/.neamcode/
  bin/
    neamcode              # CLI wrapper script
  lib/
    dist/
      index.js            # Built application
    node_modules/         # Production dependencies
    package.json          # Version manifest
  config/
    config.yaml           # User configuration (preserved on uninstall)
  VERSION                 # Installed version

Release History

Version Highlights
v0.3.5 Auto Memory System, 6-tier NEAMCODE.md, @path imports, Rules Engine
v0.3.4 Offline Auto-Recovery with Ollama fallback
v0.3.3 Cross-platform installer, CI/CD pipeline, enhanced doctor
v0.3.0 Hybrid TypeScript + C++ N-API bridge with Neam backend
v0.2.9 v0.3 specification milestone

See Releases for full changelogs.

Contributing

NeamCode is part of the neam-lang ecosystem. Contributions welcome — open an issue or PR.

License

Apache 2.0

About

NeamCode terminal client for multi-provider agentic workflows

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages