Volition

🌟 Overview

Volition is an open-source, Rust-specialized AI coding assistant that empowers developers to interact with their codebase through natural language. Built with a focus on flexibility and extensibility, Volition supports multiple AI providers and interaction strategies.

⚠ Early Development Warning: Volition is in the experimental stage. It currently lacks comprehensive safety measures and is intended for development use only. Use at your own risk.

✨ Key Features

• Rust Specialized: Optimized for Rust development workflows with deep understanding of Rust idioms and patterns
• Multi-Provider Support: Compatible with various LLM providers (Google, OpenAI, Ollama, etc.)
• Strategy Pattern Architecture: Flexible interaction models including PlanExecute and CompleteTask strategies
• MCP (Model Context Protocol) First: Native support for the emerging MCP standard
• CLI + Library Separation: Use as a command-line tool or integrate the core library into your applications
• Free and Open Source: Licensed under Apache 2.0

📦 Installation

Prerequisites

• Rust toolchain (1.70+ recommended)
• For non-local models: API keys for your preferred provider(s), set as environment variables (e.g., GEMINI_API_KEY).

From crates.io (Recommended)

Once published, you can install the command-line tool directly from crates.io:

cargo install volition-cli --locked

This will make the volition command and the associated volition-*-server binaries available in your environment (typically in $HOME/.cargo/bin, ensure this directory is in your system's PATH). Using --locked ensures you use the exact dependency versions tested for the release.

From Source

# Clone the repository
git clone https://github.com/jessebmiller/volition.git
cd volition

# Build the project
cargo build --release

# Optional: Install the binary and servers locally from source
# This makes 'volition' available in $HOME/.cargo/bin
cargo install --path volition-cli

🚀 Quick Start

Configuration

Create a Volition.toml file in your project root:

default_provider = "gemini"

system_prompt = """
You are Volition, an AI-powered Rust engineering assistant.
Your goal is to help the user understand, modify, and improve their Rust codebase.
Always follow Rust best practices and idioms.
"""

[providers]
  [providers.gemini]
  type = "gemini"
  # Make sure the environment variable below is set in your envionment or a .env file
  api_key_env_var = "GEMINI_API_KEY"
  [providers.gemini.model_config]
    model_name = "gemini-1.5-pro"
    endpoint = "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro:generateContent"
    parameters = { temperature = 0.7 }

[mcp_servers]
  # See note below on MCP Server Paths for more information
  [mcp_servers.filesystem]
  command = "volition-filesystem-server"
  [mcp_servers.git]
  command = "volition-git-server"
  [mcp_servers.search]
  command = "volition-search-server"
  [mcp_servers.shell]
  command = "volition-shell-server"


[strategies]
  [strategies.plan_execute]
  planning_provider = "gemini"
  execution_provider = "gemini"

Note on MCP Server Paths:

• The command paths under [mcp_servers] tell Volition how to launch the tools it needs (like filesystem access, git operations, etc.).
• If you installed using cargo install volition-cli, the server binaries (volition-filesystem-server, volition-git-server, etc.) are placed alongside the main volition binary, typically in $HOME/.cargo/bin/.
• If $HOME/.cargo/bin is in your system's PATH environment variable (which is common for Rust setups), you can often just use the command name directly (e.g., command = "volition-filesystem-server") as shown in the example above.
• If it's not in your PATH or you need specific paths, provide the full absolute path (e.g., command = "/path/to/your/.cargo/bin/volition-filesystem-server").
• If running from a source checkout (using cargo run), you would use relative paths to the build output, like command = "target/debug/volition-filesystem-server".
• Future versions may include automatic server discovery or management to simplify this setup.

Usage

Ensure your API keys are set as environment variables or are set in a .env file. These variable names are configured in Volition.toml (e.g., export GEMINI_API_KEY). Volition.toml should be located in the current directory or a parent directory.

Starting a New Conversation:

• Interactive Chat:

  volition
  

  (Starts a new interactive session. Type exit or press Enter on an empty line to quit. Type new to discard the current session and start fresh.)

• Single Turn (Non-interactive):

  volition --turn "Refactor the error handling in src/main.rs"
  

  (Runs a single query, prints the response, and exits. Creates a new conversation history.)

Managing Conversations:

• List Recent Conversations:

  volition list
  volition list -l 5  # List the last 5
  

• View a Specific Conversation:

  volition view <CONVERSATION_ID>
  volition view <CONVERSATION_ID> --full  # Show full message content
  

  (Replace <CONVERSATION_ID> with the actual ID from volition list)

• Resume an Interactive Conversation:

  volition resume <CONVERSATION_ID>
  

• Resume with a Single Turn (Non-interactive):

  volition resume <CONVERSATION_ID> --turn "Based on our previous discussion, add documentation."
  

• Delete a Conversation:

  volition delete <CONVERSATION_ID>
  

  (Prompts for confirmation before deleting)

Logging:

Enable more detailed logging using the -v flag.

volition -v list         # Info level
volition -vv resume <ID> # Debug level
volition -vvv --turn ... # Trace level (most verbose)

Logs are printed to stderr and also saved to a file (typically volition-app.log in your system's temporary directory).

🧩 Architecture

Volition is built with a modular architecture:

• volition-cli: Command-line interface
• volition-core: Core agent library with providers, strategies, and tools
• (Individual server crates also exist in the workspace but are built/installed via volition-cli)

🛠 Development

Building the Project

# Build all components
cargo build

# Run tests
cargo test

# Run the CLI from source (ensure Volition.toml points to target/debug servers)
cargo run -p volition-cli -- [ARGS]
# Example:
# cargo run -p volition-cli -- list -l 3

Server Components

The MCP servers are separate binaries. When running the CLI via cargo run -p volition-cli, it may not automatically find the server binaries unless they are built and their paths are configured correctly in a development Volition.toml (e.g., pointing to target/debug/volition-filesystem-server).

You can also run servers manually for testing if needed.

cargo run -p volition-filesystem-server
cargo run -p volition-git-server
cargo run -p volition-search-server
cargo run -p volition-shell-server

🤝 Contributing

Contributions are welcome! Please see our CONTRIBUTING.md for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

Distributed under the Apache License 2.0. See LICENSE for more information.

License Change Notice

Important: This project was previously released under the MIT License. As of 2025-03-28, the license has been changed to Apache License 2.0.

The Apache 2.0 license provides additional patent protections not present in the MIT license. This change was made to better protect contributors and users of this project while maintaining the open source nature of the code.

Any copies or forks of this repository created prior to this change date would still be under the MIT license terms. All new contributions and usage will be governed by the Apache License 2.0.

🔗 Links

• Discord
• GitHub Repository
• Issue Tracker
• MCP Protocol Specification

The author of Volition is looking for full time product and engineering work. Please contact him at jesse@jessebmiller.com.