Table of Contents

• What is Kwaak?
• High level features
• How is Kwaak different from other tools?
• Latest updates on our blog :fire:
• Getting started
• Requirements
  • Docker
  • Api keys
• Installation and setup
  • Homebrew
  • Linux and MacOS (using curl)
  • Cargo
  • Setup
• Running Kwaak
• How does it work?
• Configuration
  • General Configuration
  • Command Configuration
  • API Key Management
  • Docker and GitHub Configuration
  • LLM Configuration
  • Backoff Configuration
  • Other configuration
• Upcoming
• Troubleshooting & FAQ
• Community
• Contributing
• License

[![Crate Badge]][Crate] [![Contributors][contributors-shield]][contributors-url] [![Stargazers][stars-shield]][stars-url] [![MIT License][license-shield]][license-url] [![LinkedIn][linkedin-shield]][linkedin-url]

Kwaak

Burn through tech debt with AI agents!

<a href="https://github.com/bosun-ai/kwaak/issues/new?labels=bug&template=bug_report.md">Report Bug</a>
·
<a href="https://github.com/bosun-ai/kwaak/issues/new?labels=enhancement&template=feature_request.md">Request Feature</a>
·
<a href="https://discord.gg/3jjXYen9UY">Discord</a>

What is Kwaak?

Always wanted to run a team of AI agents locally from your own machine? Write code, improve test coverage, update documentation, or improve code quality, while you focus on building the cool stuff? Kwaak enables you to run a team of autonomous AI agents right from your terminal, in parallel. You interact with Kwaak in a chat-like terminal interface.

Kwaak is free and open-source. You can bring your own API keys, or your own models via Ollama.

Kwaak is aware of your codebase and can answer questions about your code, find examples, write and execute code, create pull requests, and more. Unlike other tools, Kwaak is focussed on autonomous agents, and can run multiple agents at the same time.

[!CAUTION] Kwaak can be considered alpha software. The project is under active development; expect breaking changes. Contributions, feedback, and bug reports are very welcome.

Kwaak is part of the bosun.ai project. An upcoming platform for autonomous code improvement.

Powered by Swiftide

(back to top)

High level features

• Run multiple agents in parallel
• Quacking terminal interface
• As fast as it gets; written in Rust, powered by Swiftide
• Agents operate on code, use tools, and can be interacted with
• View and pull code changes from an agent; or have it create a pull request
• Sandboxed execution in docker
• OpenAI, Ollama, Anthropic, Azure, and many other models via OpenRouter
• Python, TypeScript/Javascript, Go, Java, Ruby, Solidity, C, C++, and Rust

(back to top)

How is Kwaak different from other tools?

Kwaak focuses on out-of-your-way autonomous agents. There are great tools available to utilize AI in your own coding workflow, Kwaak does the opposite. Throw your backlog at Kwaak, so you can work on the cool stuff.

Latest updates on our blog :fire:

• Releasing kwaak with kwaak

Getting started

Requirements

Before you can run Kwaak, make sure you have Docker installed on your machine.

Docker

Kwaak expects a Dockerfile in the root of your project. If you already have a Dockerfile, you can just name it differently and configure it in the configuration file. This Dockerfile should contain all the dependencies required to test and run your code.

[!NOTE] Docker is used to provide a safe execution environment for the agents. It does not affect the performance of the LLMs. The LLMs are running either locally or in the cloud, and the docker container is only used to run the code. This is done to ensure that the agents cannot access your local system. Kwaak itself runs locally.

Additionally, the Dockerfile expects git and should be ubuntu based.

A simple example for Rust:

FROM rust:latest

RUN apt-get update && apt install git -y --no-install-recommends

COPY . /app

WORKDIR /app

If you already have a Dockerfile for other purposes, you can either extend it or provide a new one and override the dockerfile path in the configuration.

For an example Dockerfile in Rust, see this project's Dockerfile

Api keys

Additionally, you will need an API key for your LLM of choice.

If you'd like kwaak to be able to make pull requests, search github code, and automatically push to a remote, a github token.

(back to top)

Installation and setup

Pre-built binaries are available from the releases page.

Homebrew

brew install bosun-ai/tap/kwaak

Linux and MacOS (using curl)

 curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bosun-ai/kwaak/releases/latest/download/kwaak-installer.sh | sh

Cargo

Install the binary directly with binstall

cargo binstall kwaak

Or compile from source with Cargo:

cargo install kwaak

Arch Linux

The package is available in the extra repositories and can be installed with pacman:

pacman -S kwaak

Setup

Once installed, you can run kwaak init in the project you want to use Kwaak in. This will guide you through the setup process and it will help you create a configuration file. See Configuration for more customization options.

Api keys can be prefixed by env:, text: and file: to read secrets from the environment, a text string, or a file respectively.

We highly recommend taking a look at the configuration file and adjusting it to your needs. There are various options that can improve the performance and accuracy of the agents.

Running Kwaak

You can then run kwaak in the root of your project. On initial bootup, Kwaak will index your codebase. This can take a while, depending on the size. Once indexing has been completed, subsequent startups will be faster.

Keybindings:

• ctrl-s: Send the current message to the agent
• ctrl-x: Exit the agent
• ctrl-q: Exit kwaak
• ctrl-n: Create a new agent
• Page Up: Scroll chat up
• Page Down: Scroll chat down
• tab: Switch between agents

Additionally, kwaak provides a number of slash commands, /help will show all available commands.

(back to top)

How does it work?

On initial boot up, Kwaak will index your codebase. This can take a while, depending on the size. Once indexing has been completed once, subsequent startups will be faster. Indexes are stored with duckdb. Kwaak uses the index to provide context to the agents.

Kwaak provides a chat interface similar to other LLM chat applications. You can type messages to the agent, and the agent will try to accomplish the task and respond.

When starting a chat, the code of the current branch is copied into an on-the-fly created docker container. This container is then used to run the code and execute the commands.

After each chat completion, kwaak can lint, commit, and push the code to the remote repository if any code changes have been made. Kwaak can also create a pull request. Pull requests include an issue link to #48. This helps us identify the success rate of the agents, and also enforces transparency for code reviewers. This behaviour is fully configurable.

Kwaak uses patch based editing by default. This means that only the changed lines are sent to the agent. This is more efficient. If you experience issues, try changing the edit mode to whole or line.

(back to top)

Configuration

Kwaak supports configuring different Large Language Models (LLMs) for distinct tasks like indexing, querying, and embedding to optimize performance and accuracy. Be sure to tailor the configurations to fit the scope and blend of the tasks you're tackling. Configuration is done in a kwaak.toml file in the root of the project, and can be overridden by a kwaak.local.toml file and/or via ENV variables.

General Configuration

All of these are inferred from the project directory and can be overridden in the kwaak.toml configuration file.

• project_name: Defaults to the current directory name. Represents the name of your project.
• language: The programming language of the project, for instance, Rust, Go, Python, JavaScript, etc.

Command Configuration

Kwaak uses tests, coverages, and lints as an additional opportunity to steer the agent. Configuring these will (significantly) improve the agents' performance.

• test: Command to run tests, e.g., cargo test.
• coverage: Command for running coverage checks, e.g., cargo llvm-cov --summary-only. Expects coverage results as output. Currently handled unparsed via an LLM call. A friendly output is preferred
• lint_and_fix: Optional command to lint and fix project issues, e.g., cargo clippy --fix --allow-dirty; cargo fmt in Rust.

Custom tools via MCP

The community has made many amazing tools available via the MCP protocol. Kwaak can be extended with these.

Example:

[[mcp]]
# A name for your convenience
name = "server-everything"

# The command and arguments to start up the mcp server
command = "npx"
args = ["-y", "@modelcontextprotocol/server-everything"]

# Optionally whitelist or blacklist tools
filter = { type = "whitelist", tool_names = ["add"] }

# Optionally set environment variables. Values are assumed to be secret and follow the same syntax as api keys (prefixed with env:, text:, or file:)
env = {
  SECRET_CALCULATOR_API_KEY = "env:SECRET_CALCULATOR_API_KEY"
}

You can verify the mcp tools work by listing them with kwaak --allow-dirty list-tools.

API Key Management

• API keys and tokens can be configured through environment variables (env:KEY), directly in the configuration (text:KEY), or through files (file:/path/to/key).

Docker and GitHub Configuration

• docker.dockerfile, docker.context: Paths to Dockerfile and context, default to project root and Dockerfile.
• github.repository, github.main_branch, github.owner, github.token: GitHub repository details and token configuration.

LLM Configuration

Supported providers:

• OpenAI
• Ollama
• Anthropic
• Azure (AzureOpenAI)
• OpenRouter (no embeddings)

OpenAI Configuration:

[llm.indexing]
api_key = "env:KWAAK_OPENAI_API_KEY"
provider = "OpenAI"
prompt_model = "gpt-4o-mini"

[llm.query]
api_key = "env:KWAAK_OPENAI_API_KEY"
provider = "OpenAI"
prompt_model = "gpt-4o"

[llm.embedding]
api_key = "env:KWAAK_OPENAI_API_KEY"
provider = "OpenAI"
embedding_model = "text-embedding-3-large"

Ollama Configuration:

WARN: We do not recommend using the smaller models with kwaak, apart from indexing. The model should be able to make tool calls fairly reliable.

[llm.indexing]
provider = "Ollama"
prompt_model = "llama3.2"

[llm.query]
provider = "Ollama"
prompt_model = "llama3.3"
base_url = "http://localhost:11434/v1" # optional; this is the default

[llm.embedding]
provider = "Ollama"
embedding_model = { name = "bge-m3", vector_size = 1024 }

Azure Configuration:

```toml azure_openai_api_key = "env:KWAAK_AZURE_OPENAI_API_KEY"

[llm.indexing]

or override it per provider

api_key = "env:KWAAK_AZURE_OPENAI_API_KEY"

base_url = "https://your.base.url" deployment_id = "your-deployment-id" api_version