Niffler

Niffler is an AI terminal assistant written in Nim. It supports local interactive use, tool calling, reusable skills, and optional multi-agent orchestration over NATS.

Current user-facing workflows include:

• plan and code modes with stronger plan-mode protections
• reusable skills that can be loaded or downloaded on demand
• agent runtime configuration stored in markdown frontmatter
• Discord routing through the master and agent messaging flow

Core Features

• Interactive terminal assistant with conversation history
• Tool calling for shell commands, file reads, edits, creation, and web fetches
• Plan mode for analysis and task breakdown
• Code mode for implementation work
• Skills system for reusable workflow guidance
• Optional multi-agent routing with @agent commands over NATS
• Discord integration for remote access
• Database-backed conversation persistence and token usage tracking

Architecture

graph TB
    subgraph Users
        U[User Terminal]
        D[Discord Client]
    end

    subgraph Niffler Cluster
        M[Master Niffler<br/>CLI Interface]
        A1[Agent: Coder]
        A2[Agent: Researcher]
        A3[Agent: Tester]
    end

    subgraph Infrastructure
        N[NATS Server<br/>Message Broker]
        DB[(Shared Database<br/>TiDB/MySQL)]
    end

    U -->|Interactive CLI| M
    D <-->|Discord Bot| M

    M <-->|Task Dispatch| N
    A1 <-->|Task Subscription| N
    A2 <-->|Task Subscription| N
    A3 <-->|Task Subscription| N

    M <-->|Conversation & Token Tracking| DB
    A1 <-->|Task Results & State| DB
    A2 <-->|Task Results & State| DB
    A3 <-->|Task Results & State| DB

    style M fill:#f9f,stroke:#333,stroke-width:2px
    style N fill:#bbf,stroke:#333,stroke-width:2px
    style DB fill:#bfb,stroke:#333,stroke-width:2px

Key Components:

• Master Niffler: Terminal interface for user interaction, task dispatch, and Discord routing
• Agent Nifflers: Specialized workers subscribed to task channels via NATS
• NATS Server: Message broker for real-time agent communication
• Shared Database: Persistent storage for conversations, agent state, and token usage

Quick Start

1. Install prerequisites

Build requirements:

• Nim 2.2.4 or later
• Git
• Clang
• libclang development headers (libclang-dev on Debian/Ubuntu)

Runtime requirements:

• TiDB or MySQL

Optional for multi-agent mode:

• NATS Server

2. Install system libraries

macOS:

brew install cnats mariadb-connector-c pcre

Ubuntu/Debian:

sudo apt install libnats3.7t64 libnats-dev libmariadb-dev xsel libpcre3 libpcre3-dev

For a typical Ubuntu/Debian setup, this is usually enough to build and run the local assistant:

sudo apt install clang libclang-dev libmariadb-dev

If you want multi-agent mode, also install NATS support and the server:

sudo apt install libnats-dev nats-server

3. Build

nimble build

4. Initialize config

./niffler init

This creates ~/.niffler/config.yaml and the active config directories used for prompts and agent definitions.

5. Configure a model

Edit ~/.niffler/config.yaml and set either api_key directly or api_env_var.

Example:

models:
  - nickname: "openrouter-free"
    base_url: "https://openrouter.ai/api/v1"
    model: "qwen/qwen3-coder:free"
    api_env_var: "OPENROUTER_API_KEY"
    enabled: true

Then export the key:

export OPENROUTER_API_KEY="your-key-here"

6. Start Niffler

./niffler

Useful commands:

/help
/model
/new
/conv
/plan
/code

Modes

Plan Mode

/plan switches the conversation into analysis mode.

• emphasizes investigation, task breakdown, and design
• protects files that existed before the current plan session
• allows editing files created during the current plan session
• supports creating plan files that are tracked for that session

Example:

/plan
Analyze the codebase and propose the smallest safe fix.

Code Mode

/code switches back to implementation mode.

• removes plan-mode edit restrictions
• is intended for concrete file changes and execution

/code
Implement the approved fix and run the tests.

See doc/MANUAL.md for the full plan/code workflow.

Skills

Skills are reusable instruction modules that help an agent apply a specific workflow.

Common commands:

/skill list
/skill load golang
/skill show golang
/skill download vercel-labs/agent-skills --skill frontend-design

Niffler discovers skills from:

• .agents/skills/
• .claude/skills/
• ~/.agents/skills/
• ~/.niffler/skills/

See SKILLS.md and doc/MANUAL.md for details.

Multi-Agent Mode

Niffler can also run a master process and multiple named agents that communicate over NATS.

Start infrastructure

Database (choose one):

# Option 1: TiUP (recommended for production-like setup)
tiup playground --tag niffler

# Option 2: Docker
docker run -d --name tidb -p 4000:4000 pingcap/tidb:latest

# Option 3: Podman
podman run -d --name tidb -p 4000:4000 pingcap/tidb:latest

You may also need a MySQL client for initial setup:

# Ubuntu/Debian
sudo apt install mysql-client

# macOS
brew install mysql-client

Create the test database:

mysql -h 127.0.0.1 -P 4000 -u root -e 'CREATE DATABASE IF NOT EXISTS niffler_test'

NATS:

nats-server -js

Start master and agents

Terminal 1:

./niffler

Terminal 2+:

./niffler agent coder
./niffler agent researcher
./niffler agent tester

Route work from master

@coder fix the build failure in src/api.nim
@researcher find the best NATS client for Nim
@coder /task implement error handling for the API

/agents
/focus coder
fix this bug

Agent Definitions

Agent runtime configuration now lives in markdown files under the active config directory, typically ~/.niffler/<config>/agents/.

Example:

---
model: openrouter-free
allowed_tools:
  - read
  - edit
  - create
  - bash
  - list
  - fetch
auto_start: true
max_turns: 30
---

# Coder Agent

## Description
Specialized in code analysis and implementation.

## System Prompt
You are a coding expert.

Important frontmatter fields:

• allowed_tools: required tool whitelist
• model: optional model override
• auto_start: startup hint used when master.auto_start_agents is enabled
• max_turns: optional per-agent turn limit override
• capabilities: optional advanced permission layer for action-backed orchestration tools

capabilities is usually unnecessary for ordinary coding agents. Normal tools like read, edit, create, bash, fetch, and todolist are controlled by allowed_tools.

The markdown file is the authoritative runtime definition for the agent.

Discord

Discord support is optional and works alongside the master and agent flow.

See doc/DISCORD_SETUP.md for setup and command details.

Documentation

• doc/MANUAL.md - full user manual
• doc/EXAMPLES.md - workflows and examples
• doc/TOOLS.md - built-in tools reference
• SKILLS.md - skills system details
• ACTIONS.md - action and orchestration model
• doc/DISCORD_SETUP.md - Discord setup
• doc/MCP_SETUP.md - MCP server integration
• doc/CONTRIBUTING.md - contributor guide
• doc/README.md - documentation index

Development

nimble test
nim c src/niffler.nim
nimble build
./niffler --loglevel=DEBUG --dump

License

MIT License. See LICENSE.