Skip to content

getting-started.md

Latest commit

 

History

History
115 lines (77 loc) · 4.17 KB

getting-started.md

File metadata and controls

115 lines (77 loc) · 4.17 KB
Raw

Getting started

Bcode is currently an early alpha distributed from source. There are no published binaries or crates yet.

Prerequisites

Install:

Bcode's full distribution build also compiles bundled OCR support and may require a native C/C++ toolchain and CMake. The terminal-agent build below avoids that additional packaging.

Build the terminal agent

Clone Bcode and build the TUI with its statically bundled providers, tools, commands, and integrations:

git clone https://github.com/BSteffaniak/bcode.git
cd bcode
cargo build --release -p bcode \
  --no-default-features \
  --features app,static-bundled-plugins \
  --bin bcode

Run it:

./target/release/bcode

On Windows:

.\target\release\bcode.exe

The first normal interactive launch opens Bcode's setup flow. It detects existing configuration and environment hints, then walks through provider, model, authentication, permissions, optional session imports, and plugin choices.

Running bcode after setup opens the TUI. The client starts a matching local daemon automatically when needed; normal use does not require a separate server command.

Choose a provider

The bundled distribution includes two provider integrations:

  • OpenAI-compatible: OpenAI API keys, ChatGPT browser or device-code login, xAI API keys, and configurable compatible endpoints.
  • Amazon Bedrock: models available through the Bedrock ConverseStream API and the active AWS credential chain, plus Anthropic and OpenAI models served through the Bedrock Mantle endpoint. See Bedrock-hosted OpenAI models for the GPT-5.6 tier and other OpenAI models.

For OpenAI or ChatGPT authentication, the canonical CLI flow is:

bcode auth providers
bcode auth login openai
bcode auth status openai

Use --method api_key, --method chatgpt, or --method device to choose a specific registered OpenAI authentication path. Provider secrets are enrolled through Bcode's auth flow rather than written directly into ordinary configuration.

Environment-based configuration is also supported, including BCODE_OPENAI_API_KEY, OPENAI_API_KEY, BCODE_OPENAI_MODEL, and the corresponding Bedrock and xAI variables. Run bcode model list to inspect models visible through the configured provider.

Start working

Open Bcode in a repository:

cd path/to/repository
/path/to/bcode

Useful entry points:

  • Run bcode -n to create a new session immediately.
  • Run bcode -n --worktree my-task to start a session in a new Git worktree.
  • Press Ctrl-F in the TUI to open the command palette.
  • Use /plan for read-oriented analysis and /build when implementation is allowed.
  • Use /sessions to switch sessions and /compact to compact long context.
  • Press Esc to interrupt active work.

Bcode asks before sensitive operations according to the active agent's policy. Permission dialogs show the normalized operation and support one-time, batch, and remembered decisions when applicable. See Permissions for configuration and precedence.

Full distribution build

The complete release feature composition adds bundled OCR runtimes, Mermaid rendering, and the optional web renderer:

cargo build --release -p bcode --features distribution --bin bcode

Release automation and supported artifact targets are documented in Release builds. Public artifacts have not been published yet.

Configuration

Bcode loads global and repository-local bcode.toml files. Common locations include:

~/.config/bcode/bcode.toml
<repository>/bcode.toml
<repository>/.bcode/bcode.toml

The documentation site generates its complete configuration and CLI references from the Rust schema and command tree. Until that site is publicly deployed, generate it locally with:

cargo run --release -p bcode_docs_site --bin bcode-docs-site -- gen --output dist

Focused guides: