spec-ai

(Experimental)

Documentation

For detailed documentation, see:

• docs/ARCHITECTURE.md - System architecture and component overview
• docs/CONFIGURATION.md - Complete configuration guide
• docs/SETUP.md - Detailed setup instructions
• docs/SELF-INIT.md - Bootstrap self-discovery process
• docs/VERIFY.md - Testing and verification guide
• docs/COLLECTIVE.md - Multi-agent coordination and emergent specialization
• docs/AGENT_SKILLS.md - Durable agent maintenance skills and governance modes
• docs/ACP_INTEGRATION_LIFT.md - Investigation of ACP (Agent Client Protocol) compatibility

Example configurations are available in examples/configs/:

• config.openai.example.toml - OpenAI provider setup
• config.lmstudio.toml - Local LM Studio configuration
• config.multi_model.example.toml - Multi-model reasoning setup
• config.graph.example.toml - Knowledge graph configuration

Example code demonstrating various features can be found in examples/code/.

Architecture

Workspace Structure

crates/
├── spec-ai-cli/             # Binary crate (user-facing CLI / REPL)
├── spec-ai-core/            # Agent runtime, tools, embeddings, CLI helpers
├── spec-ai-config/          # Config models, persistence layer, shared types
├── spec-ai-knowledge-graph/ # Knowledge graph storage, vector clocks, types
├── spec-ai-graph-sync/      # Distributed knowledge graph synchronization engine
├── spec-ai-collective/      # Emergent collective intelligence (capabilities, learning, consensus)
├── spec-ai-policy/          # Policy engine and plugin system
├── spec-ai-plugin/          # Custom tool plugin system (dynamic library loading)
├── spec-ai-api/             # HTTP/mesh server and sync coordinator
├── spec-ai-tui/             # Terminal UI framework built on crossterm
├── spec-ai-tui-app/         # Interactive terminal application
├── spec-ai-oui/             # Optical UI framework for AR/glasses displays
├── spec-ai-oui-app/         # OUI demo application with OpenTelemetry visualization
└── spec-ai/                 # Public library crate re-exporting the pieces above

docs/, examples/, specs/, etc.

cargo run -p spec-ai-cli launches the CLI from source, while cargo test exercises every crate in the workspace.

Quick Start

Installation

Download Pre-built Binaries

Pre-built binaries are available for macOS, Linux, and Windows. Download the latest release for your platform from the GitHub Releases page.

1. Download the appropriate archive for your platform
2. Extract the archive
3. Move the spec-ai binary to a directory in your PATH (e.g., /usr/local/bin on macOS/Linux)

# Example for macOS/Linux
tar -xzf spec-ai-<version>-<platform>.tar.gz
sudo mv spec-ai /usr/local/bin/

Install via Cargo

cargo install spec-ai --features bundled
# OR (requires additional configuration of duckdb)
cargo binstall spec-ai

Configuration

On first run, spec-ai will automatically create a spec-ai.config.toml file with default settings in your current directory. You can edit this file to customize your configuration.

Alternatively, place your configuration in ~/.spec-ai/spec-ai.config.toml for user-wide settings, or use the --config flag to specify a custom location.

Using Custom Config Files:

# Specify a custom config file (created with defaults if it doesn't exist)
spec-ai --config /path/to/my-config.toml

# Use different configs for different projects
spec-ai -c ./project-a.toml
spec-ai -c ./project-b.toml

Configuration Precedence

Configuration is loaded in the following order (highest precedence first):

1. Command-Line Flag - --config <PATH> (if specified)
2. Environment Variables - AGENT_* prefix (e.g., AGENT_MODEL_PROVIDER=openai)
3. Current Directory - ./spec-ai.config.toml
4. Home Directory - ~/.spec-ai/spec-ai.config.toml
5. Environment Variable - CONFIG_PATH environment variable
6. Embedded Default - A default configuration is embedded in the binary and created if no config file exists

Running

# Start a chat session
spec-ai

# Start a chat session using the configuration in the specified file
spec-ai --config /path/to/config.toml

# Show help
spec-ai --help

Command-Line Options:

• -c, --config <PATH> - Specify a custom configuration file path
• -h, --help - Display usage information

Expected output:

Configuration loaded:
  Database: /Users/you/.agent_cli/agent_data.duckdb
  Model Provider: mock
  Temperature: 0.7
  Logging Level: info
  UI Theme: default

Structured Specs

You can capture complex tasks in reusable .spec files and hand them directly to the agent:

1. Write a TOML file with the .spec extension describing the goal, tasks, and expected deliverables.
2. Start the CLI (cargo run) and enter /spec run path/to/plan.spec (or the shorthand /spec path/to/plan.spec).

Example spec:

name = "Docs refresh"
goal = "Document the new spec runner command across the README"

context = """
Capture the CLI command syntax and show a working example.
"""

tasks = [
  "Explain how to invoke the command",
  "Provide a sample `.spec` file",
  "Highlight the goal/deliverables requirement"
]

deliverables = [
  "Updated README summary of the feature",
  "Code snippets demonstrating the workflow"
]

Specs must include a goal plus at least one entry in tasks or deliverables. The CLI prints a preview before executing the spec with the current agent.

To run spec files, use the spec-ai run command:

spec-ai run                      # runs examples/spec/smoke.spec by default
spec-ai run spec/               # run all *.spec files inside spec/
spec-ai run custom.spec          # run a specific spec file
spec-ai run spec1.spec spec2.spec # run multiple spec files

The default examples/specs/smoke.spec is purposely simple and works against the mock provider so you can verify the CLI still functions after code changes.

Agent Profiles

Define multiple agents with different personalities and capabilities:

[agents.coder]
prompt = "You are a helpful coding assistant"
temperature = 0.3
allowed_tools = ["file_read", "file_write", "bash", "file_extract"]
memory_k = 10

[agents.researcher]
prompt = "You are a research assistant"
temperature = 0.8
denied_tools = ["bash", "file_write"]
memory_k = 20

prompt_user is implicitly allowed (unless you add it to denied_tools) so agents can always escalate to a human for clarification.

Custom Tool Plugins

You can extend the agent with custom tools implemented as Rust dynamic libraries. Plugins are auto-discovered from a configured directory at startup.

Configuration:

[plugins]
enabled = true
custom_tools_dir = "~/.spec-ai/tools"
continue_on_error = true        # Continue if some plugins fail to load
allow_override_builtin = false  # Prevent plugins from replacing built-in tools

Creating a Plugin:

1. Create a new Rust library with crate-type = ["cdylib"]
2. Implement the ABI-stable plugin interface (see crates/spec-ai-plugin/examples/greeting_plugin/)
3. Build with cargo build --release
4. Copy the library to your plugins directory:
   • macOS: ~/.spec-ai/tools/libmy_plugin.dylib
   • Linux: ~/.spec-ai/tools/libmy_plugin.so
   • Windows: ~/.spec-ai/tools/my_plugin.dll

Example Plugin:

use abi_stable::std_types::{RStr, RString, RVec};

// Define your tool's execute function
extern "C" fn my_tool_execute(args_json: RStr<'_>) -> PluginToolResult {
    // Parse args, do work, return result
    PluginToolResult::success("Tool executed!")
}

// Export the plugin module
#[abi_stable::export_root_module]
fn get_library() -> PluginModuleRef {
    // Return module with api_version, plugin_name, get_tools
}

Plugin tools can be referenced by name in agent profiles via allowed_tools and denied_tools just like built-in tools.

Testing

Run all tests:

cargo test --all-targets

Run API tests (requires api feature):

cargo test --features api

Run specific test suites:

cargo test --lib plugin
cargo test --lib policy
cargo test --test policy_integration_tests

Development

Code Quality

• Comprehensive error handling with anyhow and thiserror
• Type-safe configuration with validation
• Idiomatic Rust with clippy compliance
• Full test coverage for critical paths

Design Principles

• Separation of Concerns: Config, persistence, and business logic are cleanly separated
• Testability: All components can be tested in isolation
• Extensibility: Easy to add new agents, tools, and providers
• Safety: Strong typing, validation, and error handling throughout

License

MIT License

Copyright (c) 2025 spec-ai Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing

Create an issue. Open a PR.