Getting Started with Bismuth

Installation

You can install Bismuth using the installation script or by installing the CLI directly. The installation script provides the easiest way to get started and includes an interactive quickstart guide.

Quick Installation

Install using the quick installation script:

        nickgregory@MBP ➜ npx bismuthcli install
    

By default, this installs to ~/bin or ~/.local/bin. You can customize the installation directory:

        nickgregory@MBP ➜ npx bismuthcli --dir /custom/path
    

The installer will:

1. Download the appropriate binary for your platform (supported platforms include macOS arm64/x64 and Linux arm64/x64)

2. Add the installation directory to your PATH if needed (modifying .zshrc/.zprofile or .bashrc/.bash_profile as appropriate)

3. Launch the interactive quickstart guide (can be disabled with --no-quickstart)

Installation Options

The installer supports several options:

Initial Setup

After installation, you'll need to authenticate with the Bismuth platform and either try our sample project or import your own repository.

Authentication

Log in to the Bismuth platform:

        nickgregory@MBP ➜ biscli login
    

Billing

After logging in, the CLI will check your available credits. New accounts start with 100 credits. If you need more credits, you can purchase them using:

        nickgregory@MBP ➜ biscli billing refill
    

Working with the Chat Interface

The chat interface is your primary way of interacting with Bismuth. Understanding how to use it effectively will help you get the most out of Bismuth's capabilities.

Starting a Chat Session

First import your project into Bismuth. (Optional: You'll be asked if you want to send us your codebase this is strictly for better static analysis and search. We do not train on any of your code.)

        nickgregory@MBP ➜ biscli import './your-project'
    

You can start a chat session for any imported repository using the chat command. Bismuth will load the repository's context and be ready to help with your codebase:

        nickgregory@MBP ➜ biscli chat --repo path/to/your/repo
    

During the chat session, Bismuth maintains an understanding of your entire codebase, allowing it to make informed suggestions and modifications. When you request changes, Bismuth considers the full context of your code, including dependencies, related files, and existing patterns.

Effective Communication with Bismuth

When working with Bismuth, it's helpful to be specific about what you want to achieve. Consider these examples of effective requests:

Chat Commands

The chat interface provides several commands to help you manage your session:

         
/help           Show available commands and usage information
/status         Check the current repository and Bismuth's status
/feedback       Send feedback or report issues
/docs           Open the Bismuth documentation
/session {name} Switch to a chat session with a specific name
/diff           Show the diff of the last changes made by Bismuth
/refill         Refill your credits
/exit           Exit the chat session

    

Sample Project Tutorial

The sample project is a great way to understand how Bismuth works in practice. It walks you through adding features and fixing bugs in a simple TODO application. This tutorial uses approximately 50 credits, giving you a hands-on experience with Bismuth's capabilities while leaving credits for your own projects.

Setting Up the Sample Project

First, clone and set up the sample TODO application:

        nickgregory@MBP ➜ git clone https://github.com/BismuthCloud/quickstart-sample quickstart-sample && cd quickstart-sample && npm install && npm run dev
    

Once the development server is running, you'll see a simple TODO application in your browser. This application provides basic task management functionality that we'll enhance with Bismuth's help.

Importing the Project to Bismuth

Now that the project is running, let's import it to Bismuth. The --upload flag ensures Bismuth has access to all necessary files:

        nickgregory@MBP ➜ biscli import './quickstart-sample' --upload
    

Adding a Feature with Bismuth

Let's enhance the TODO app by adding due dates to tasks. Open the Bismuth chat interface:

        nickgregory@MBP ➜ biscli chat --repo './quickstart-sample'
    

In the chat interface, request the new feature with this detailed prompt:

Bismuth will now:

1. Analyze your request and plan the implementation

2. Review the existing codebase to understand the current structure

3. Generate and test the necessary changes

4. Present you with a diff of the proposed changes

When Bismuth shows you the diff, review the changes and press 'y' to accept them. The changes will be automatically applied to your codebase.

Fixing a Bug with Bismuth

Next, we'll experience how Bismuth helps fix bugs. We'll introduce a simple bug and then ask Bismuth to help us fix it:

1. Open src/App.tsx in your editor

2. Find the handleToggleTask function (around line 27)

3. Delete the line containing: saveTasks(updatedTasks);

This creates a bug where task completion states aren't persisted. Ask Bismuth to investigate:

Bismuth will analyze the issue, identify the missing save call, and propose a fix. Review the diff and accept it by pressing 'y' to restore the persistence functionality.

Check that everything works and then this concludes the sample project tutorial.

You've now experienced how Bismuth can help you add features and fix bugs in your codebase. The next section will cover project management commands to help you maintain a clean and organized workspace including cleaning up the sample project.

Project Management

Bismuth provides several commands to help you manage your projects effectively. Understanding these commands will help you maintain a clean and organized workspace.

Importing Projects

When importing a project, you have several options to control how Bismuth interacts with your codebase:

        nickgregory@MBP ➜ # Basic import
biscli import path/to/repo

# Import with file upload (recommended)
biscli import path/to/repo --upload

    

The --upload flag is recommended as it ensures Bismuth has access to all necessary files, including those that might be ignored by version control but are important for understanding the project context.

Managing Your Workspace

Once you've completed the sample project tutorial, you can clean up your workspace by removing it from Bismuth:

        nickgregory@MBP ➜ biscli project delete quickstart-sample
    

Bismuth can be used with many types of projects beyond JavaScript frontends. You can use it to refactor Java webservers, write Python backends, or even create utility programs in C.

To start working with your own project, import it to Bismuth:

        nickgregory@MBP ➜ biscli import path/to/your/repo
    

Remember these helpful commands while working with Bismuth:

         
/help     - Get information about available commands
/feedback - Send feedback or report bugs