AI Assistants

This environment includes AI-powered development tools to enhance your ROS2 development workflow.

Access Methods

There are two ways to access AI tools in this environment:

ai

pair

nom develop

direnv allow

Note: The devshell commands are always available when you enter the development environment. The extended aliases require home-manager module configuration.

aichat - Foundation AI CLI

aichat is the default AI assistant - a tiny, provider-agnostic CLI that works with multiple AI providers.

Supported Providers

ANTHROPIC_API_KEY

OPENAI_API_KEY

GOOGLE_API_KEY

AZURE_OPENAI_API_KEY

Quick Start

# Set your API key (choose your provider)
export ANTHROPIC_API_KEY="your-key-here"
# or
export OPENAI_API_KEY="your-key-here"

# Basic usage
ai "explain what ROS2 topics are"

# Code assistance
ai-code "write a ROS2 publisher node in Python"

# Code review
ai-review "review this launch file for best practices"

# Explain code
cat src/my_node.py | ai-explain

Available Aliases

ai

aichat

ai-code

aichat --role coder

ai-explain

aichat --role explain

ai-review

aichat --role reviewer

Configuration

aichat stores configuration in

~/.config/aichat/config.yaml

# Example configuration
model: claude                         # Short model name (aichat resolves to latest)
save: true
highlight: true
temperature: 0.7

# Custom roles
roles:
  - name: ros2-expert
    prompt: |
      You are a ROS2 expert. Help with:
      - Node development (Python/C++)
      - Launch files
      - Message/Service definitions
      - Best practices for robotics

Note: aichat uses short model names (e.g.,

claude

gpt-4

gemini-pro

Using with Ollama (Local Models)

For offline/private AI assistance:

# Install Ollama (if not already)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a coding model
ollama pull codellama

# Use with aichat
aichat --model ollama:codellama "write a ROS2 subscriber"

ROS2-Specific Usage

# Explain a ROS2 concept
ai "explain ROS2 QoS profiles"

# Generate a launch file
ai-code "create a launch file that starts a camera node and image processor"

# Debug an error
ai "why am I getting 'could not find package' in colcon build"

# Review code
cat src/robot_controller/robot_controller/controller.py | ai-review

Tips

1. Pipe code for context:

   cat file.py | ai "explain this"

2. Use roles for consistency:

   ai-code

   for generation,

   ai-review

   for feedback
3. Save sessions: Use

   aichat -s session-name

   to continue conversations
4. Local models: Use Ollama for private/offline work

Aider - AI Pair Programming

Aider is a Git-integrated AI pair programmer that edits code in your repo with automatic commits.

Quick Start

# Start aider in current directory
pair

# Work on specific files
pair src/my_package/my_node.py

# Voice-to-code mode (requires portaudio)
pair-voice

# Watch mode - auto-commit on file changes
pair-watch

# Use specific model
aider --model claude-3-sonnet-20240229
aider --model gpt-4-turbo

Key Features

Available Aliases

pair

aider

pair-voice

aider --voice

pair-watch

aider --watch

pair-claude

aider --model claude-3-sonnet-20240229

pair-gpt4

aider --model gpt-4-turbo

ROS2-Specific Usage

# Edit a ROS2 node
pair src/my_robot/my_robot/controller.py
> "Add a service server that accepts velocity commands"

# Modify launch files
pair src/my_robot/launch/robot.launch.py
> "Add a parameter for robot_name"

# Update CMakeLists.txt
pair src/my_robot/CMakeLists.txt
> "Add the new action interface dependency"

Configuration

Create

~/.aider.conf.yml

# Default model
model: claude-3-sonnet-20240229

# Auto-commit settings
auto-commits: true
auto-lint: true

# Editor integration
edit-format: diff

# Voice settings (if using --voice)
voice-language: en

# Dark mode for terminal
dark-mode: true

Environment Variables

# API keys (set in .envrc or shell profile)
export ANTHROPIC_API_KEY="sk-ant-..."  # For Claude
export OPENAI_API_KEY="sk-..."         # For GPT-4
export DEEPSEEK_API_KEY="..."          # For DeepSeek

Voice Mode Requirements

Voice-to-code requires:

• portaudio

  (included in devshell)
• Microphone access
• API key for speech-to-text (uses provider's audio API)

Environment Variables

Add to your shell profile or

.envrc

# Choose one provider
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

# Optional: Set default model
export AICHAT_MODEL="claude-3-sonnet-20240229"

Home-Manager Configuration

If using home-manager, enable the AI modules to get all aliases:

{
  # Enable aichat with aliases (ai, ai-code, ai-explain, ai-review)
  programs.aichat = {
    enable = true;
    settings = {
      model = "claude";                 # Short model name
      save = true;
      highlight = true;
    };
  };

  # Enable aider with aliases (pair, pair-voice, pair-watch, pair-claude, pair-gpt4)
  programs.aider = {
    enable = true;
    settings = {
      model = "claude-3-sonnet-20240229";
      auto-commits = true;
      dark-mode = true;
    };
  };
}

Module Locations:

• modules/common/ai/aichat.nix

  - aichat configuration

• modules/common/ai/aider.nix

  - aider configuration

• modules/common/ai/default.nix

  - AI module aggregator

LocalAI - Local LLM Inference

LocalAI provides an OpenAI-compatible API server for running LLMs locally. It's the recommended inference backend for this environment.

Quick Start

# Start LocalAI server
localai start

# Check status
localai status

# List available models
localai models

# Stop server
localai stop

Features

Configuration

LocalAI uses the models directory at

~/.local/share/localai/models

# Set custom models path
export LOCALAI_MODELS_PATH="/path/to/models"

# Download a model (example)
curl -L "https://huggingface.co/TheBloke/Mistral-7B-v0.1-GGUF/resolve/main/mistral-7b-v0.1.Q4_K_M.gguf" \
  -o ~/.local/share/localai/models/mistral-7b.gguf

Integration with Other Tools

# Use LocalAI with aichat
export OPENAI_API_BASE="http://localhost:8080/v1"
aichat --model local-model "Hello"

# Use LocalAI with aider
OPENAI_API_BASE=http://localhost:8080/v1 aider

Port Configuration

Documentation: See

docs/adr/adr-006-agixt-integration.md

AGiXT - AI Agent Platform

AGiXT is a powerful AI Agent Automation Platform that enables building and orchestrating complex AI workflows.

Quick Start

# Ensure LocalAI is running first
localai start

# Start AGiXT services
agixt up

# Check service status
agixt status

# View logs
agixt logs

# Stop services
agixt down

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AGiXT Stack                               │
├─────────────┬─────────────┬─────────────┬───────────────────┤
│  AGiXT API  │  AGiXT UI   │ PostgreSQL  │      MinIO        │
│   :7437     │   :3437     │   :5432     │    :9000/:9001    │
└──────┬──────┴──────┬──────┴──────┬──────┴─────────┬─────────┘
       │             │             │                │
       └─────────────┴─────────────┴────────────────┘
                            │
                    ┌───────┴───────┐
                    │   LocalAI     │
                    │    :8080      │
                    └───────────────┘

Port Configuration

Environment Variables

# .env.agixt or exported
export AGIXT_URL="http://localhost:7437"
export AGIXT_API_KEY="agixt-dev-key"
export LOCALAI_URL="http://localhost:8080"

Management Commands

# Full command reference
agixt up      # Start all services
agixt down    # Stop all services
agixt logs    # Follow logs
agixt status  # Show container status
agixt shell   # Shell into AGiXT container

ROS2 Integration

The AGiXT Rust SDK bridge (

rust/agixt-bridge/

# Build the bridge
cd rust/agixt-bridge
cargo build

# Run example
cargo run --example basic_chat

Key files:

• rust/agixt-bridge/

  - Rust SDK integration

• docker-compose.agixt.yml

  - Docker Compose configuration

• .env.agixt.example

  - Environment template

• docs/adr/adr-006-agixt-integration.md

  - Architecture decision record

Related Skills

• Distributed Systems - NATS, Temporal
• Observability - Monitoring AI services
• Rust Tooling - AGiXT Rust SDK development