beamlab 0.2.2

A production-grade CLI AI coding agent

⚡ BeamLab CLI

A production-grade, autonomous AI coding agent for your terminal.

BeamLab is a high-performance CLI agent designed to live in your codebase. It doesn't just chat—it searches, reads, reasons, and executes code changes with surgical precision. Powered by a multi-provider "cascade", it ensures you always have a brain online, even when APIs are down.

---

🚀 Quick Start

1. Installation

Install directly via pip:

pip install beamlab

2. Configure Your Keys

BeamLab uses environment variables for security. Add these to your shell profile (.zshrc, .bashrc, or PowerShell $PROFILE):

export LONGCAT_API_KEY="your-key-here"

Or use the .agent.toml configuration file in your project root:

[model]
longcat_api_key = "your-key-here"

3. Launch

Navigate to any project directory and start the session:

beamlab

---

🧠 Functional Overview

BeamLab operates as a Stateful Agentic Loop. When you give it a task, it follows a rigorous internal cycle:

1. Context Retrieval: It perform semantic searches across your repo using a local FAISS vector store.
2. Reasoning: It uses "Thinking" models to architect a solution.
3. Tool Execution: It uses specialized tools for file I/O, code searching, shell commands, and web research.
4. Verification: It can run tests and verify its own changes before handing the reins back to you.

---

� Usage Guide

Starting a Session

When you launch BeamLab in a project directory, it will:

• Load or create a session for that project
• Restore your previous conversation history (if any)
• Initialize the context with your project files

Session Management

Sessions are isolated per project. Each session maintains its own:

• Conversation history
• Context files
• File modification undo stack

Use these commands to manage sessions:

Command	Description	Usage
/new	Start a fresh session	/new "Fixing Bug"
/sessions	List all stored sessions	/sessions
/switch	Switch to a different session	/switch 2
/clear	Wipe current chat history	/clear

Model Selection

View available models and switch between them:

/model

Switch to a specific model:

/model longcat:Flash-Thinking

Context Management

Add files to the context for the agent to reference:

/add src/main.py
/add tests/test_*.py

You can also reference files inline in your prompts:

Explain how @main.py works

File Operations

BeamLab can read, write, and edit files. All write operations require approval by default.

To undo the last file modification:

/undo

---

�🛠️ Interactive Slash Commands

While in the BeamLab REPL, you can use / commands to manage your session:

Command	Description	Usage
/help	List all available commands	/help
/sessions	List all stored sessions for this project	/sessions
/new	Start a fresh named session	/new "Fixing Bug"
/switch	Switch to a different session by ID or number	/switch 2
/model	Show or change the active LLM	/model
/add	Manually pin a file to the context	/add src/main.py
/undo	Roll back the last file modification	/undo
/clear	Wipe the current chat history	/clear

---

⚙️ Configuration (.agent.toml)

BeamLab looks for a .agent.toml file in your project root for local overrides.

[model]
primary     = "LongCat-Flash-Chat"
temperature = 0.1

[safety]
require_approval_for_writes = true   # Set to false for full autonomy
require_approval_for_shell  = true

[indexing]
exclude = [".git", "node_modules", "dist"]

Configuration Options

Model Settings:

• primary: The primary model to use
• temperature: Sampling temperature (0.0 to 1.0)
• longcat_api_key: Your LongCat API key (can also use env var)

Safety Settings:

• require_approval_for_writes: Require confirmation before file writes
• require_approval_for_shell: Require confirmation before shell commands

Indexing Settings:

• exclude: Patterns to exclude from codebase indexing

---

🛡️ Safety First

BeamLab is built with a Security-First mindset:

• Write Guard: Every file modification requires your explicit approval by default.
• Shell Guard: No rm -rf or arbitrary commands run without a "Y/N" confirmation.
• Path Restricted: The agent is restricted to working within your project root unless specified otherwise.

---

🔧 Advanced Features

Provider Cascade

BeamLab automatically handles provider failures by cascading to available alternatives:

1. LongCat (primary) - Your main provider
2. Ollama (local) - Running locally for offline usage

If the primary provider fails, BeamLab will automatically try the next available provider.

Session Persistence

Your sessions are automatically saved and restored:

• Sessions persist across restarts
• Each project has isolated sessions
• Switch between sessions without losing context

Intelligent Context

BeamLab builds context intelligently:

• Indexes your codebase for semantic search
• Tracks file references in conversation
• Maintains conversation history within sessions

---

👤 Author

Muhammad Yasir (devxyasir)
Email: [e-mail]
GitHub: devxyasir/beamlab

---

Developed with love for the Python community. ⚡🚀