Nexus

The Most Powerful AI CLI Tool for Developers

Install • Features • Usage • Config • Plugins • Contributing

Nexus is a terminal-based AI assistant that helps you write, edit, and understand code. It connects to local models via Ollama or cloud providers like OpenAI and Anthropic, giving you a ChatGPT-like experience directly in your terminal.

 ┌─────────────────────────────────────────────────────────┐
 │  nexus  🔧  ollama/qwen2.5-coder                      │
 │─────────────────────────────────────────────────────────│
 │                                                         │
 │  >_ Nexus                                               │
 │  model:     qwen2.5-coder /models to change            │
 │  directory: ~/projects/my-app                           │
 │  agent:     build                                      │
 │                                                         │
 │  Tip: Shift+Tab to switch agent • Tab cycle perms      │
 │                                                         │
 │─────────────────────────────────────────────────────────│
 │ ❯ Ask me anything...                                   │
 │                                                         │
 │ Tab:Auto • ↑↓ scroll • Enter send            0 msgs    │
 └─────────────────────────────────────────────────────────┘

Features

🤖 AI Agent Loop

Nexus can autonomously plan, execute, and verify multi-step tasks:

You: refactor the auth module to use JWT tokens

[THINK] Analyzing the current auth implementation...
[PLAN] 1. Read auth.go 2. Add JWT library 3. Update handlers 4. Run tests
[ACT] Reading auth.go...
[VERIFY] File read successfully
[ACT] Writing updated auth.go with JWT support...
[VERIFY] Tests passing
[REFLECT] Auth module successfully refactored to use JWT

💭 Thinking Stream

Watch the AI reason in real-time:

💭 Thinking (842ms):
  Let me analyze the codebase structure...
  I see this is a Go project with multiple packages...
  The user wants to add authentication...

🔧 Built-in Tools

Nexus has 8 built-in tools the AI can use automatically:

Tool	Description
`read_file`	Read file contents
`write_file`	Create or overwrite files
`edit_file`	Precise text replacement
`delete_file`	Remove files
`list_dir`	List directory contents
`run_command`	Execute shell commands
`grep`	Search with ripgrep
`glob`	Find files by pattern

🔐 Secure Vault

Encrypted credential storage with AES-256:

/vault unlock my-master-password
/vault set github_token ghp_xxxxxxxxxxxx
/vault set api_key sk-xxxxxxxxxxxx

💰 Cost Tracking

Track token usage and costs per session:

/costs

Session Usage:
  gpt-4o: 15 requests, ~45000 tokens, $0.2340
  Total: $0.2340
  Duration: 12m 34s

🔌 Plugin System

Extend Nexus with custom tools:

~/.config/nexus/plugins/my-tool/plugin.json

📺 File Watcher

Monitor files for changes:

/watch          # Start watching
/watch stop     # Stop watching

🎨 Interactive Diff

Side-by-side diff viewer:

/diff main.go   # Show diff for file

Installation

Install Script (Recommended)

curl -fsSL https://raw.githubusercontent.com/MrModelOS/Nexus/master/install.sh | sh

Pre-built Binaries

Download from GitHub Releases:

# Linux (amd64)
curl -L https://github.com/MrModelOS/Nexus/releases/download/v1.0.0/nex-linux-amd64 -o nex
chmod +x nex
sudo mv nex /usr/local/bin/

# macOS (arm64)
curl -L https://github.com/MrModelOS/Nexus/releases/download/v1.0.0/nex-darwin-arm64 -o nex
chmod +x nex
sudo mv nex /usr/local/bin/

Build from Source

git clone https://github.com/MrModelOS/Nexus.git
cd Nexus
make install

Or manually:

go build -o nexus .
cp nexus ~/.local/bin/

Prerequisites

Go 1.21+ (for building from source)
Ollama (for local models) — Install Ollama
ripgrep (optional, for search) — sudo pacman -S ripgrep

Quick Start

1. Configure Nexus

# Interactive setup
nex init

# Or edit config directly
vim ~/.config/nexus/config.yaml

2. Pull a Model

ollama pull qwen2.5-coder

3. Start Nexus

nex

4. Try These Commands

/help           # Show all commands
/models         # Pick a model
/search fmt     # Search code
/context        # Show project structure
/agent refactor the main module    # Multi-step task

Usage

Basic Chat

❯ Write a function to parse JSON

Reference Files

❯ Analyze @main.go and suggest improvements

Run Commands

❯ What does this project do? /context

Multi-Step Agent

❯ /agent Add unit tests for the parser module

Search Code

❯ /search TODO

Configuration

Config file: ~/.config/nexus/config.yaml

default_model: qwen2.5-coder
temperature: 0.7
system_prompt: You are Nexus, a helpful AI assistant.

providers:
  ollama:
    type: ollama
    base_url: http://localhost:11434
    models:
      - qwen2.5-coder
      - llama3.2
      - gemma3:1b

  openai:
    type: openai
    base_url: https://api.openai.com
    api_key: sk-your-key-here
    models:
      - gpt-4o
      - gpt-4o-mini

  anthropic:
    type: anthropic
    base_url: https://api.anthropic.com
    api_key: sk-ant-your-key-here
    models:
      - claude-sonnet-4-20250514
      - claude-3-5-haiku-20241022

Commands Reference

Navigation

Key	Action
`↑/↓`	Scroll output
`PgUp/PgDn`	Half page scroll
`Enter`	Send message
`Tab`	Cycle permission mode
`Shift+Tab`	Toggle agent (build/plan)
`Esc`	Dismiss hints / quit

Slash Commands

Command	Description
`/help`	Show all commands
`/clear`	Clear chat history
`/models`	Interactive model picker
`/search <query>`	Search files with ripgrep
`/context`	Show project structure
`/git`	Show git status
`/commit`	Generate commit message
`/review`	Review staged changes
`/autofix`	Run tests/linters
`/agent <goal>`	Start agent loop
`/think`	Toggle thinking display
`/vault`	Credential management
`/costs`	Show token usage
`/plugins`	List installed plugins
`/prompts`	Manage prompt templates
`/watch`	Start file watcher
`/diff <file>`	View file diff
`/perm`	Manage permissions
`/skills`	Load skill files
`/sessions`	Manage saved sessions
`/compact`	Compress history
`/quit`	Exit Nexus

File References

Prefix with @ to include file content:

Explain @src/main.go

Skill Activation

Prefix with $ to load a skill:

$review This code for security issues

Plugins

Creating a Plugin

Create ~/.config/nexus/plugins/my-tool/plugin.json:

{
  "name": "my-tool",
  "description": "My custom tool",
  "version": "1.0.0",
  "tools": [
    {
      "name": "deploy",
      "description": "Deploy to production",
      "schema": {
        "type": "object",
        "properties": {
          "env": {"type": "string"}
        }
      },
      "command": "echo Deploying to $NEXUS_TOOL_ARGS"
    }
  ]
}

Using Plugins

/plugins           # List installed plugins
/tools             # See all available tools

The AI can then use your custom tools automatically.

Skills

Skills are markdown files that provide specialized instructions.

Creating a Skill

Create ~/.config/nexus/skills/review.md:

---
name: review
description: Code review assistance
---

When reviewing code:
1. Check for security vulnerabilities
2. Look for performance issues
3. Verify error handling
4. Suggest improvements

Using Skills

$review Check this function for issues

Agent Modes

Build Mode (Default)

Full access to file system and commands. The AI can read, write, and execute freely.

Plan Mode

Read-only analysis. The AI can only read files and suggest changes without modifying anything.

Toggle with Shift+Tab.

Permission Modes

Mode	Description
Manual	Ask before every action
Accept Edits	Auto-approve file edits
Plan	Read-only, suggest only
Auto	Full auto-execution

Cycle with Tab.

Project Structure

nexus/
├── main.go                 # Entry point
├── cmd/
│   ├── root.go            # Root command
│   ├── ask.go             # Quick ask command
│   ├── models.go          # List models
│   └── init.go            # Interactive setup
├── client/
│   ├── client.go          # Ollama client
│   └── multi.go           # Multi-provider
├── config/
│   └── config.go          # YAML config
├── internal/
│   ├── tui.go             # Main TUI (1700+ lines)
│   ├── tools.go           # Tool registry
│   ├── agent.go           # Agent loop
│   ├── thinking.go        # AI reasoning
│   ├── plugins.go         # Plugin system
│   ├── vault.go           # Encrypted vault
│   ├── costs.go           # Cost tracking
│   ├── prompts.go         # Prompt templates
│   ├── watcher.go         # File monitoring
│   ├── diff.go            # Diff viewer
│   ├── permissions.go     # Access control
│   ├── context.go         # Context management
│   ├── search.go          # Ripgrep integration
│   ├── session.go         # Session persistence
│   ├── skills.go          # Skill system
│   ├── compact.go         # History compression
│   ├── agents.go          # Agent profiles
│   ├── project.go         # Project context
│   ├── git.go             # Git integration
│   ├── mcp.go             # MCP protocol
│   ├── autofix.go         # Auto-fix loop
│   └── banner.go          # Startup banner
└── assets/
    └── nexus-logo.png     # Logo

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

Fork the repository
Create your feature branch (git checkout -b feature/amazing)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing)
Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

Bubble Tea — TUI framework
Lip Gloss — Styling
Glamour — Markdown rendering
Ollama — Local AI models
Ripgrep — Fast search

Made with ❤️ by the Nexus community

Name		Name	Last commit message	Last commit date
.nexus		.nexus
client		client
cmd		cmd
config		config
internal		internal
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
main.go		main.go

Latest commit

History

Folders and files

Repository files navigation

Nexus

Features

🤖 AI Agent Loop

💭 Thinking Stream

🔧 Built-in Tools

🔐 Secure Vault

💰 Cost Tracking

🔌 Plugin System

📺 File Watcher

🎨 Interactive Diff

Installation

Install Script (Recommended)

Pre-built Binaries

Build from Source

Prerequisites

Quick Start

1. Configure Nexus

2. Pull a Model

3. Start Nexus

4. Try These Commands

Usage

Basic Chat

Reference Files

Run Commands

Multi-Step Agent

Search Code

Configuration

Commands Reference

Navigation

Slash Commands

File References

Skill Activation

Plugins

Creating a Plugin

Using Plugins

Skills

Creating a Skill

Using Skills

Agent Modes

Build Mode (Default)

Plan Mode

Permission Modes

Project Structure

Contributing

License

Acknowledgments

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages