🦞

Lobster Code
The AI coding agent that lives on your computer.

An AI agent that writes code, manages files, uses git and automates your work. 100% local, zero cloud, zero cost. Web UI + Ollama, ready in 2 minutes.

✦ Open Source — MIT License
⚡ Powered by Ollama — 100% local
# Clone the repository
git clone https://github.com/SuperSapiensAi/LobsterCode.git
cd LobsterCode/ui

# Install Ollama and pull a model with tool calling
ollama pull gemma4:latest

# Launch Lobster Code
bash start-agent.command
Features

Not a chatbot. An agent that actually works.

Writes code, runs commands, versions, protects your files and learns your project.

🧬

Project DNA

Scans your project and builds a persistent profile: stack, conventions, linter, test framework, structure. The agent writes code that respects your style.

Prompt Templates

Smart templates that adapt to your stack. React? It suggests components. Python? It offers venv and tests. Zero configuration.

🚀

Multi-Turn Agent Loop

It doesn't stop at the first response. Executes up to 10 consecutive tool-calling turns to complete complex tasks autonomously.

🐜

Built-in Git

Status, diff, commit and log right from the sidebar. No terminal, no context switching.

Snapshot & Rollback

Every action creates an automatic snapshot. If something goes wrong, roll back with one click. Zero risk.

🔒

Workspace Isolation

The agent only accesses the folders you grant. Three permission levels with real enforcement: writes limited to workspace, MCP tools only in full-access, built-in anti-escalation.

🛠

7 Native Tools

bash, read_file, write_file, edit_file, list_directory, search_files, glob_search. Everything you need to work on code.

🧠

Session Memory

Saves notes and context in .lobster/context.md within your workspace. Notes, decisions and preferences persist across sessions.

📋

Diff Preview

Every change shows a line-by-line diff. You always know what changed, before and after.

🔌

MCP Protocol

Connect external tools via Model Context Protocol. Database, GitHub, Slack, browser — one JSON file and the agent uses them as native tools.

🛡

Native Security

Protected system paths, blocked destructive commands, atomic writes, anti-escalation. The agent cannot self-promote or break your OS.

👁

Real-Time Streaming

Responses arrive word by word via Server-Sent Events. Watch the agent think and act in real time.

🔮

Setup Wizard

Checks Ollama, verifies RAM, recommends the best model and downloads it with one click. Up and running in 2 minutes.

See how it works

Real agent loop with tool calling, diff preview and automatic snapshots.

Lobster Code — 🦞 Ollama · gemma4:latest
🚀 Ollama · gemma4:latest · Permissions: workspace-write
👤 Create a React counter component with TypeScript and tests
# Agent detects: React + TypeScript + Jest
🔧 bash → mkdir -p src/components
🔧 write_file → src/components/Counter.tsx (38 lines)
+ export const Counter: React.FC = () => { ... }
🔧 write_file → src/components/Counter.test.tsx
✅ Component created! Snapshot saved (3 files) · Rollback available
Architecture

Minimal architecture, maximum power

Vanilla JS web UI, Python stdlib backend, Ollama for AI.

🐍

Python

Pure stdlib backend, zero pip install

🦞

Ollama

Local LLMs with native tool calling

🌐

Vanilla JS

No-framework frontend, SSE streaming

🔒

3 Permission Levels

Read-only, workspace-write (path enforcement), full-access (with confirmation)

Choose your brain

Only models with verified native tool calling. The wizard suggests the best one for your RAM.

🏆

Qwen 2.5 Coder 14B

The best for coding. Native tool calling, fast and accurate.

Coding Tools
💎

Gemma 4 12B

By Google. Excellent multilingual, native tool calling, 128K context.

General Tools 128K
🌊

Mistral 7B

Versatile and fast. Native tool calling, great balance of speed and quality.

General Tools Fast
🤖

Llama 3.3 70B

By Meta. Native tool calling, powerful and versatile. Requires 48GB+ RAM.

General Tools 128K
🔮

Codestral 22B

By Mistral AI, specialized for coding. Supports 80+ programming languages.

Coding Tools
Comparison

Lobster Code vs. other tools

What you get by choosing a local, free and open source agent.

🦞 Lobster Code Cursor Claude Code Ollama Chat
Cost Free $20/mo Pay-per-use Free
Privacy (local)
Agent loop with tools
Web UI IDE CLI
Built-in Git
Snapshot & Rollback
Permission system
Open source MIT
Zero config
MCP / Extensibility
How to use it

From the command line to complete projects

Not a chatbot. A colleague that executes, versions and protects your work.

🏗

Project Scaffolding

Creates complete structures with context-awareness. The agent detects the stack and adapts its actions accordingly.

"Create a REST API in FastAPI with JWT auth and pytest tests"
🐛

Debug & Fix

Reads the code, finds the bug, fixes it with a diff preview and creates a snapshot for rollback.

"Login is broken, check auth.py and fix it"
📂

Safe Refactoring

Automatic snapshot before every change. If you don't like the result, roll back with one click.

"Refactor utils/ by splitting functions into domain modules"
📈

Data Analysis

Processes CSV files, generates charts, computes statistics. All local — your data stays yours.

"Analyze sales.csv, show monthly trend and top 5 products"
🐜

Git Workflow

Commit, branch, log from the UI. Automatically generates changelogs by analyzing recent commits.

"Generate a changelog from the develop branch and commit it"
🎨

Frontend from Scratch

HTML, CSS, JS — components, animations, responsive. Shows a diff for every file it touches.

"Create a landing page for my portfolio with dark mode"
"The best tool is one that never asks you to leave your flow. Lobster lives where you work — in your files, with your data, all local. No cloud spying on you, no subscription holding you back."

— The Lobster team

🚀 Discover Lobster Manager too
🚀 Desktop App for macOS

Lobster Manager
The control center for your dev environment.

Native desktop app built with Electron + React + TypeScript. Manage projects, Docker, ports, system resources and AI advisor — all in one interface. Open source, 100% local, zero cloud.

✦ Open Source — MIT License 🔒 100% Local — Zero Cloud ⚡ Free forever
⬇ Download for macOS Source Code
🔍

Auto-Discovery Projects

Automatically detects all your projects, their stack, framework, active ports and associated Docker containers.

🚦

Real-Time Dashboard

Green/yellow/red traffic light for each project. Port status, containers and git branch updated in real time.

🐳

Docker Manager

Start, stop, restart and view container logs. Manage Docker Compose with one click. No more terminal.

🔌

Port Monitor

Who's using which port? Detects conflicts, shows the responsible process and lets you kill it from the UI.

🧠

Smart Advisor AI

Intelligent project analysis with suggestions, priority triage and security reports — powered by Ollama.

🦞

LobsterCode Built-in

The coding agent right inside the app. Tool calling, git, snapshot and rollback without leaving the Manager.

📝

.lobster.md per Project

Notes, stack, diary and AI instructions for each project. Auto-generated and kept up to date.

👤

MY-PROFILE.md

Your personal profile for AI: who you are, how you work, your active projects. Auto-generated.

🔔

Notifications & Monitoring

Real-time alerts when a project starts, stops or a container enters an error state.

See what the Manager does

Lobster Manager — 🦞 Dashboard
🚀 Auto-Discovery · Found 5 projects · 3 active
🔍 Scan ~/Developer — React, FastAPI, Go detected
🔌 Port Monitor → :3000 (next-app) · :8080 (api) · :5432 (postgres)
🐳 Docker → 4 containers running · 1 warning (high memory)
# Smart Advisor analyzes the “e-commerce” project
🧠 Advisor → 2 port conflicts detected · 1 container needs restart
+ .lobster.md generated for “e-commerce” (stack, deps, notes)
✅ Dashboard updated · Notifications: 1 alert · System stable

Native stack, native performance

Electron

Native cross-platform desktop app

React + TypeScript

Modern, type-safe, component-based UI

🐳

Docker SDK

Container management without terminal

🦞

Ollama

AI advisor and built-in LobsterCode

Real scenarios, every day

🔍

Auto discovery

Open the Manager and instantly see all your projects with stack, active ports and associated Docker containers.

Finds 12 projects in ~/Developer in 3 seconds
🔌

Port conflicts

A service won't start? The Manager shows you who's using that port and you can kill the process with one click.

:3000 occupied by node — kill and restart
🐳

Docker without terminal

Start, stop, restart, logs and health checks for containers. Docker Compose with one click. No more docker ps.

Restart the database when tests fail
🧠

AI that understands your projects

The Smart Advisor analyzes each project, suggests optimizations, detects security issues and generates reports.

“Redis container using too much RAM, suggestion: set maxmemory”
📝

Automatic documentation

Every project gets its own .lobster.md with stack, dependencies, notes and AI instructions. Auto-generated and updatable.

Context file ready for any AI or new developer
📈

Resource monitoring

CPU, RAM and disk in real time. Alerts when a container or process consumes too much. Dashboard with green/yellow/red traffic lights.

Alert: postgres using 90% of allocated RAM

Install Lobster Manager

# Clone and run in dev mode
git clone https://github.com/SuperSapiensAi/LobsterCode.git
cd LobsterCode/lobster-utility
npm install
npm run dev

# Or build the native macOS app
bash build-app.sh

Ready to get started?

Lobster Code and Lobster Manager are free, open source and ready to use. Zero configuration, no account, no subscription.

GitHub Repo Install Code → Install Manager →