01 getting started

Getting Started

Bucket Agent (bucket) is an open, multiprovider terminal AI coding agent. It runs as a TUI (Terminal User Interface) that understands your codebase, executes shell commands, edits files, searches the web, and manages tasks.

You can use it interactively as a full-screen TUI, run it headlessly for scripting and CI/CD, or integrate it into editors via the Agent Client Protocol (ACP).

No xAI account is required. Use it with Ollama locally, or any OpenAI-compatible backend.

---

Installation

Install the latest stable release (macOS, Linux, or Windows via Git Bash):

curl -fsSL https://raw.githubusercontent.com/julesklord/bucket-agent/main/scripts/install.sh | bash

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/julesklord/bucket-agent/main/scripts/install.sh | bash -s 0.2.0

On Windows (PowerShell), use the native PowerShell installer:

irm https://raw.githubusercontent.com/julesklord/bucket-agent/main/scripts/install.ps1 | iex

Install a specific version:

$env:BUCKET_VERSION="0.2.0"; irm https://raw.githubusercontent.com/julesklord/bucket-agent/main/scripts/install.ps1 | iex

The PowerShell installer automatically adds %USERPROFILE%\.bucket\bin to your User PATH. Alternatively, install via Git for Windows (Git Bash) or MSYS2 using the bash script above. WSL users get the Linux binary automatically.

Verify the installation:

bucket --version

Update to the latest version at any time:

bucket update

---

Building from source

Requirements:

• Rust — the toolchain is pinned by rust-toolchain.toml; rustup installs it automatically.
• DotSlash — install it and ensure dotslash is on your PATH before building.

cargo install dotslash

# Build + launch the TUI
cargo run -p bucket-bin

# Release binary: target/release/bucket
cargo build -p bucket-bin --release

---

Quickstart with Ollama

The fastest path to a working local agent:

# 1. Start Ollama
ollama serve
ollama pull qwen2.5-coder:latest

# 2. Configure Bucket
mkdir -p ~/.bucket
cat > ~/.bucket/config.toml <<'EOF'
[models]
default = "ollama-coder"

[model.ollama-coder]
model    = "qwen2.5-coder:latest"
base_url = "http://localhost:11434/v1"
name     = "Qwen 2.5 Coder (Ollama)"
EOF

# 3. Launch
bucket

Press Enter and start coding. No API keys. No account.

---

First Launch

Start Bucket by running:

bucket

On first launch, Bucket opens your browser to authenticate with bucket.com. After you sign in, Bucket stores your credentials in ~/.bucket/auth.json, where they persist across sessions. Bucket refreshes your credentials automatically and prompts you to sign in again when they can no longer be renewed.

If you prefer API key authentication (e.g., for CI/CD or environments without a browser), set the BUCKET_API_KEY environment variable instead:

export BUCKET_API_KEY="bucket-..."
bucket

See Authentication for the full set of auth options including OIDC, external auth providers, and device code flow.

---

Basic Interaction

Once authenticated, Bucket presents a full-screen TUI with two main areas:

• Scrollback -- the conversation history showing your prompts, Bucket's responses, tool calls, file edits, and more.
• Prompt -- the input area at the bottom where you type messages.

Type a message and press Enter to send it. Bucket reads files, runs commands, and edits code as needed. Each tool run streams into the scrollback in real time.

Press Tab to move focus between the prompt and the scrollback. While a turn is running, Esc cancels it (the exception is fullscreen vim scrollback mode, where mid-turn Esc is a no-op; minimal mode cancels even with vim on); Ctrl+C cancels once the composer is empty — with a draft, the first press only clears it. Idle, press Esc twice within 800ms to clear a non-empty prompt, or (with an empty prompt and conversation messages) to open rewind — see Keyboard Shortcuts. With the scrollback focused, use the arrow keys to select entries and to collapse or expand them. To navigate with j/k and fold with h/l instead, enable Vim mode.

File References

Use @ in your prompt to attach files:

@src/main.rs              # Attach a file
@src/main.rs:10-50        # Attach lines 10-50
@src/                     # Browse a directory

The @ operator opens a fuzzy file picker. By default it respects .gitignore and hides dotfiles. Prefix with ! to search hidden files:

@!.github                 # Search hidden files
@!.env                    # Attach a .env file

Permissions

By default, Bucket asks for permission before executing shell commands or editing files. You can approve individually or toggle always-approve mode:

• Press Ctrl+O to toggle always-approve mode
• Use the --yolo flag at launch: bucket --yolo
• Type /always-approve in the prompt to toggle the mode

---

Key Concepts

Sessions

Every conversation is a session. Sessions are automatically saved to ~/.bucket/sessions/ and can be resumed later. Each session tracks the full conversation history, tool calls, file edits, and task state.

• Start a new session: Ctrl+N or /new
• Resume a previous session: /resume in the TUI, or --resume <ID> from the CLI
• Continue the most recent session: bucket -c

Scrollback

The scrollback is the main display area. It shows:

• User prompts -- your messages, rendered as sticky headers
• Agent messages -- Bucket's responses with full markdown rendering and syntax highlighting
• Thinking blocks -- Bucket's reasoning process (collapsible)
• Tool calls -- file edits (with inline diffs), command executions, search results, and more
• Task lists -- TODO items tracking progress

Collapse or expand the selected entry with the Left/Right arrow keys (or h/l and e in Vim mode). In Vim mode, press y to copy its content and Y to copy its metadata (for example, the command that ran). Press Enter to open it in the fullscreen viewer (in any mode).

Tools

Bucket has built-in tools for:

Tool	Description
read_file / search_replace	Read and edit files with line-precise changes
grep	Regex search across your codebase (powered by ripgrep)
list_dir	List directory contents
run_terminal_command	Execute shell commands
web_search / web_fetch	Search the web and fetch URLs
todo_write	Create and manage task lists
spawn_subagent	Spawn parallel subagent sessions
memory_search	Search cross-session memory

Tools can be extended with MCP servers for integrations like GitHub, databases, and more.

Slash Commands

Type / in the prompt to access commands. These provide quick actions without writing a full prompt:

/model bucket-build                 # Switch model
/compact                          # Compress conversation history
/always-approve                   # Toggle always-approve mode
/new                              # Start a new session

See Slash Commands for the complete reference.

---

Common Launch Options

# Launch the interactive TUI and submit an initial prompt as the first turn
bucket "fix the failing auth test and run it"

# Initial prompt in a new git worktree. Use --worktree=<name> (with `=`) so the
# prompt isn't swallowed as the worktree name — `bucket -w "refactor module X"`
# would treat "refactor module X" as the worktree label, not the prompt.
bucket --worktree=feat "refactor module X"

# Base the worktree on a specific branch (e.g. main) instead of the current HEAD:
bucket -w --ref main "implement feature from main"


# Start in a specific project directory
bucket --cwd ~/projects/my-app

# Add project-specific rules
bucket --rules "Always use TypeScript. Prefer functional components."

# Auto-approve all tool executions
bucket --yolo

# Use a specific model
bucket -m bucket-build

# Resume a previous session
bucket --resume <session-id>

# Continue the most recent session
bucket -c

# Experimental scrollback-native render mode. Sticky: plain `bucket` reopens in
# the mode last chosen via --minimal/--fullscreen (or /minimal//fullscreen).
bucket --minimal

# Back to the standard fullscreen TUI (and make it sticky again)
bucket --fullscreen

# Headless mode (for scripts)
bucket -p "Explain this codebase"

---

Headless Mode

Run Bucket non-interactively for scripting, CI/CD, and automation:

bucket -p "Your prompt here"

Output formats:

Format	Flag	Description
plain	(default)	Human-readable text
json	--output-format json	Single JSON object with text, stopReason, sessionId, and requestId
streaming-json	--output-format streaming-json	NDJSON event stream for real-time processing

Example CI/CD usage:

bucket -p "Review changes for bugs" --output-format json --yolo | jq -r '.text'

---

Project Rules (AGENTS.md)

Add per-project instructions by creating an AGENTS.md file in your repository. Bucket reads these files and injects their contents as a project-instructions message at the start of the conversation:

~/.bucket/AGENTS.md           # Global rules (apply to all projects)
<repo-root>/AGENTS.md       # Repository-level rules
<cwd>/AGENTS.md             # Directory-level rules (highest priority)

Deeper files take precedence. Bucket also reads CLAUDE.md files for compatibility.

---

Where to Go Next

Document	What You Will Learn
Authentication	Browser login, API keys, OIDC, external auth, device code flow
Keyboard Shortcuts	Complete reference for all key bindings
Slash Commands	All available / commands
Configuration	config.toml, pager.toml, environment variables