NerveTerm

中文 | English

This is a proof-of-concept (PoC) project. NerveTerm is experimental software under active development. Many features are incomplete or unstable. It is NOT suitable for production use. Use at your own risk.

Overview

NerveTerm is an AI-powered shell wrapper that provides intelligent command completion, automatic error diagnosis, and natural language interaction. Built with Go and Bubble Tea, it aims to bridge the gap between traditional shell workflows and large language model assistance.

Known Issues

• Tab completion is currently non-functional - The inline suggestion system uses a different mechanism; traditional tab completion for file paths is not implemented
• Ghost text reliability varies - AI responses may sometimes duplicate typed text or provide irrelevant suggestions
• cd command - Uses a workaround; shell state management needs proper implementation
• Chinese input - May have display issues in certain terminal configurations

Architecture

NerveTerm follows a clean architecture with functional programming patterns (using fp-go):

graph TB
    subgraph TUI["TUI Layer (Bubble Tea)"]
        MVU["Model ── View ── Update"]
    end

    subgraph Ports["Ports (Interfaces)"]
        AIProv["AIProvider"]
        ShellExec["ShellExecutor"]
    end

    subgraph Adapters["Adapters (Implementations)"]
        OpenAI["OpenAI Adapter"]
        LocalShell["Local Shell Executor"]
    end

    subgraph Core["Core (Business Logic)"]
        Prompt["Prompt Builder"]
        Intent["Intent Detection"]
        Response["Response Parser"]
    end

    TUI --> Ports
    Ports --> Adapters
    Ports --> Core
    Adapters --> Core

Loading

Key Components

• tui/ - Bubble Tea application (Model-View-Update)
• adapters/ - External service integrations (OpenAI, shell)
• core/ - Business logic (prompt building, intent detection)
• ports/ - Interface definitions for dependency inversion
• config/ - Configuration management

Installation

Requirements

• Go 1.25 or later
• OpenAI API key (or compatible API)
• Unix-like system (Linux, macOS)

Build from Source

git clone https://github.com/somhairle/nerveterm.git
cd nerveterm
go build ./cmd/nerveterm

Run Directly

go run cmd/nerveterm/main.go

Configuration

NerveTerm uses a TOML configuration file located at:

~/.config/nerveterm/config.toml

The configuration is auto-generated on first run with default values:

[ai]
provider = "openai"
api_key = "sk-..."           # Your OpenAI API key
base_url = ""                # Optional: custom API endpoint
model = "gpt-4o"

[shell]
shell = "zsh"                # Default shell to use
working_dir = "~"            # Initial working directory

[ui]
theme = "dracula"             # Color theme: dracula, light, etc.

Environment Variables

You can also configure via environment variables:

export NERVETERM_API_KEY="sk-..."
export NERVETERM_MODEL="gpt-4o"
export NERVETERM_SHELL="zsh"

Development

Project Structure

nerveterm/
├── adapters/           # External service implementations
│   ├── openai/        # OpenAI API adapter
│   └── shell/         # Shell execution adapter
├── application/       # Application orchestration
├── cmd/               # CLI entry points
│   └── nerveterm/
├── config/            # Configuration management
│   └── record_ops.go  # Functional record operations (fp-go)
├── core/              # Domain logic
│   ├── detector/      # Executable detection
│   ├── intent/        # Intent analysis with predicates
│   ├── prompt/        # Prompt building with monoids
│   ├── response/      # LLM response parsing
│   ├── shell/         # State monad for shell state
│   └── types/         # Shared types with fp-go helpers
├── docs/              # Documentation
│   └── plans/         # Design documents
├── ports/             # Interface definitions
├── testutil/          # Testing utilities (assertions)
└── tui/               # Terminal UI (Bubble Tea)
    ├── history.go     # Functional history operations
    ├── lenses.go      # Immutable state updates (optics)
    ├── model.go
    ├── traversal.go   # Batch operations (optics)
    ├── update.go
    └── view.go

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./tui -v

Roadmap

Priority	Feature	Status
High	Working Tab completion (file paths)	Blocked
High	Stable ghost text suggestions	In Progress
Medium	Multi-line command input	Planned
Medium	Command history search (Ctrl+R)	Planned
Medium	Configurable keybindings	Planned
Low	Alternative LLM providers (Anthropic, etc.)	Planned
Low	Session persistence	Planned
Low	Plugin system	Planned

Contributing

Development Setup

# Clone the repository
git clone https://github.com/somhairle/nerveterm.git
cd nerveterm

# Install dependencies
go mod download

# Run the application
go run cmd/nerveterm/main.go

Code Style

• Follow Go conventions (gofmt, golint)
• Use functional patterns from fp-go where appropriate
• Write tests for new features
• Update documentation for API changes

Design Documents

• Ghost Completion Design - Detailed design for the ghost text completion feature

References

• Bubble Tea - TUI framework
• fp-go - Functional programming library for Go
• go-openai - OpenAI API client

License

MIT License - see LICENSE for details.

Copyright (c) 2026 Somhairle H. Marisol