Getting Started

HelixMind is an open-source AI coding CLI with spiral context memory: the only AI coding tool that truly remembers your codebase, your patterns, and your decisions across sessions.

Prerequisites

• Node.js 18+ (LTS recommended)
• An API key from one of: Anthropic, OpenAI, Groq, DeepSeek, Together AI, OpenRouter
• Or Ollama installed locally for fully offline use

Installation

npm install -g helixmind

Verify the installation:

helixmind --version

First Launch. Choose Your Path

When you start HelixMind for the first time, you'll see a choice screen:

Option 1: Login (Recommended)

Free account. unlocks the full experience:

• Jarvis: autonomous coding agent
• Validation Matrix: automatic code validation
• Security Monitor: continuous vulnerability scanning
• Autonomous Mode: find & fix issues on its own
• 3D Brain Management: multiple brains, renaming, visualization
• Live Brain WebSocket: real-time brain updates

No credit card. No trial. Free forever. Works offline after first login.

# Login anytime
helixmind login

Option 2: Open Source

No account needed. start coding immediately:

• AI Agent + 22 Tools
• Spiral Memory (1 local brain per project)
• All providers (Anthropic, OpenAI, Ollama)
• Bug Journal + Browser Control
• Sessions + Checkpoints

Features like Jarvis, Validation, Security Monitor, and Autonomous Mode are not available in Open Source mode. Run helixmind login anytime to upgrade. it's free.

See Authentication for details on tiers and feature gating.

Quick Start

# Start interactive chat
hx

# Send a single message
hx -m "Explain the auth flow in this project"

# YOLO mode. skip ALL permission prompts
hx --yolo

# Skip permission prompts (but still ask for dangerous operations)
hx -s

Project Setup

Initialize HelixMind in your project for project-local memory:

cd your-project
helixmind init

This creates a .helixmind/ directory containing:

• spiral.db: Your project's spiral memory database
• context.md: Custom instructions for the AI about your project

Edit .helixmind/context.md to tell HelixMind about your project conventions, architecture, and preferences. This file is included in every conversation context.

Provider Configuration

Set your preferred LLM provider:

# Anthropic (default, recommended)
helixmind config set provider anthropic
helixmind config set apiKey sk-ant-...

# OpenAI
helixmind config set provider openai
helixmind config set apiKey sk-...

# Ollama (fully offline, no API key needed)
helixmind config set provider ollama

# Groq (fast inference)
helixmind config set provider groq
helixmind config set apiKey gsk_...

# DeepSeek
helixmind config set provider deepseek
helixmind config set apiKey sk-...

See Providers for the full list of supported models per provider.

Your First Session

1. Navigate to your project directory
2. Run hx to start a chat
3. Ask the AI to explore your codebase: "What does this project do?"
4. The AI reads files, analyzes code, and builds spiral memory
5. In your next session, the AI already knows your project

What Makes HelixMind Different

Unlike other AI coding tools that start fresh every session, HelixMind maintains a 6-level spiral memory:

Level	Name	What It Stores
L1	Focus	What you're working on right now
L2	Active	Recent patterns and decisions
L3	Reference	Stable architecture knowledge
L4	Archive	Historical context
L5	Deep Archive	Compressed summaries
L6	Web Knowledge	Auto-fetched documentation and web insights

Your context promotes when accessed frequently and decays when unused. just like human memory.

MCP Server Mode

HelixMind also works as an MCP server, giving other AI tools access to your spiral memory:

# Claude Code
claude mcp add spiral-context -- npx -y spiral-context-mcp

# Cursor. add to .cursor/mcp.json
# VS Code. add to .vscode/mcp.json
# Windsurf. add to ~/.codeium/windsurf/mcp_config.json

See MCP Integration for complete setup instructions.

Next Steps

• Authentication. Login, API keys, and subscription tiers
• Remote Access. Connect from your phone or any device
• Spiral Memory. Deep dive into the 6-level memory system
• CLI Reference. All commands, flags, and options
• Agent Tools. The 22 tools the AI agent uses
• Brain Visualization. Real-time 3D brain viewer
• Providers. Configure Anthropic, OpenAI, Ollama, and more