中文 | 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.

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.

• 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

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

• 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

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

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

go run cmd/nerveterm/main.go

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.

You can also configure via environment variables:

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

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

# Run all tests
go test ./...

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

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

# 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

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

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

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

MIT License - see LICENSE for details.

Copyright (c) 2026 Somhairle H. Marisol