Layered Code

Created By

layered-flow7 months ago

Software development through AI-assisted coding with the Model Context Protocol (MCP)

Content

⚠️ Work in Progress ⚠️

This project is currently under active development. Features, APIs, and documentation may change frequently. While we welcome feedback and contributions (see Contributing), please note that this software is not yet ready for production use. This banner will be removed once we reach version 1.0.

🔍 What is Layered Code?

Traditional development with AI can feel chaotic - losing context, making large unfocused changes, or struggling to track what actually worked. Layered Code solves this by transforming how you build and evolve software through the Model Context Protocol (MCP). This protocol enables AI assistants to maintain deep contextual awareness of your codebase while making focused, traceable changes.

💬 How You Interact with Layered Code

Layered Code is designed to be used primarily through conversational AI interfaces that support the Model Context Protocol (MCP). Rather than memorizing complex commands or navigating intricate UIs, you simply describe what you want to build in natural language.

Primary interaction method:

🗣️ Natural language conversations with AI assistants like Claude Desktop
🔌 MCP integration provides the AI with direct access to your codebase and layered history
🎯 Intent-driven development - describe your goals, and the AI handles the technical implementation

Example conversation:

"I want to redesign the homepage with a modern hero section, update the navigation menu, and add a testimonials carousel below the fold"

The AI, equipped with Layered Code's MCP tools, can:

Understand your current page structure and styling
Access the history of previous design layers and decisions
Create a new layer with the homepage redesign
Handle HTML structure changes, CSS updates, and asset organization
Preserve your existing content while enhancing the visual design

While a CLI interface is available for direct tool access, the conversational AI experience through MCP is where Layered Code truly shines - enabling you to focus on what you want to build rather than how to build it.

🎯 Motivation

Layered Code provides an open approach that gives you the freedom to choose your own tools, hosting providers, and development workflows: Your code, your tools, your choice.

🔓 Forever Free & Open Source: Layered Code will always remain completely free and open source
🛠️ Technology Agnostic: Works with any language, framework, or development environment
🤝 Human-AI Partnership: Designed for seamless collaboration between developers and AI agents
📊 Full Traceability: Track feature evolution and maintain contextual awareness across your entire codebase
🚀 Zero Vendor Lock-in: Use any hosting provider, development environment, or toolchain

🏗️ Building from Source

To build Layered Code from source:

# Clone the repository
git clone https://github.com/layered-flow/layered-code.git
cd layered-code

# Build with make (downloads ripgrep binaries automatically)
make build

# Or build for all platforms
make build-all

# Run tests
make test

📦 Installation

Prerequisites

No additional dependencies required - ripgrep is automatically bundled with pre-built binaries and installed as a dependency via Homebrew

Option 1: macOS/Linux via Homebrew (Recommended)

brew update
brew tap layered-flow/layered-code
brew install layered-code

Note: Homebrew will automatically install ripgrep as a dependency.

Option 2: Install Script (macOS/Linux)

For system-wide installation (recommended):

curl -fsSL https://raw.githubusercontent.com/layered-flow/layered-code/main/scripts/install.sh | sudo bash

This installs the binaries to /usr/local/bin for easy access from anywhere.

If you prefer to install in the current directory instead, omit sudo:

curl -fsSL https://raw.githubusercontent.com/layered-flow/layered-code/main/scripts/install.sh | bash

Note: This script downloads a self-contained binary with ripgrep bundled.

Option 3: Pre-built Binaries

Download the appropriate archive for your platform from the GitHub releases page. Each archive contains both the layered-code binary and a bundled rg (ripgrep) binary:

macOS (Intel): layered-code_Darwin_x86_64.tar.gz
macOS (Apple Silicon): layered-code_Darwin_arm64.tar.gz
Linux (x86_64): layered-code_Linux_x86_64.tar.gz
Linux (ARM64): layered-code_Linux_arm64.tar.gz
Windows (x86_64): layered-code_Windows_x86_64.zip
Windows (ARM64): layered-code_Windows_arm64.zip (uses x64 ripgrep binary via emulation)

Setup steps:

macOS/Linux:

Extract the archive: tar -xzf layered-code_*.tar.gz
Make both binaries executable: chmod +x layered-code rg
Move both binaries to the same directory:
- For user installation: mkdir -p ~/bin && mv layered-code rg ~/bin/
- For system-wide installation: sudo mv layered-code rg /usr/local/bin/
Ensure the location is in your PATH for easy access

Windows:

Extract the zip file (contains layered-code.exe and rg.exe)
Move both executables to the same convenient location (e.g., C:\Users\YourUsername\bin\)
Add the directory to your PATH environment variable:
- Open "Environment Variables" in System Properties
- Add the directory containing both executables to your PATH

Important: Keep both layered-code and rg (ripgrep) binaries in the same directory for proper functionality.

✨ Quick Start with Claude Desktop

While there are plans to support open source models through Ollama, Claude Desktop currently provides the best support for the Model Context Protocol that Layered Code relies on.

Install Claude Desktop
Enable Developer Mode:
- Open Claude Desktop
- Go to Settings
- Navigate to the "Developer" tab
- Enable "Developer Mode" if not already enabled
Install layered-code: Follow the Installation instructions above and note the path to your binary
Configure MCP Server:
- Open Claude Desktop settings → Developer → Edit Config
- Add to claude_desktop_config.json:

Configure MCP Server in Claude Desktop

Add the following to your claude_desktop_config.json (under Settings → Developer → Edit Config), adjusting the command path as appropriate for your installation and platform:

Platform/Install Method	"command" value example
macOS/Linux (Homebrew)	`layered-code`
macOS/Linux (Manual/Binary)	`/usr/local/bin/layered-code`
Windows	`C:\\Users\\YourUsername\\bin\layered-code.exe`

Note for Windows: Use the full path with double backslashes (\\) in the "command" value.

Example configuration:

{
  "globalShortcut": "",
  "mcpServers": {
    "layered-code": {
      "command": "<see table above>",
      "args": ["mcp_server"]
    }
  }
}

Restart Claude Desktop completely (Windows may require you to "end task" on any Claude background tasks)
Verify: Check for "layered-code" in Claude's tools menu

🌐 Chrome Extension for Live Preview

The Layered Code Chrome extension enables real-time previewing of changes made through MCP. When you edit files through Claude Desktop, the extension automatically refreshes your browser to show the changes instantly.

Installation Options:

Option 1: Chrome Web Store (Recommended)

Install directly from the Chrome Web Store: https://chromewebstore.google.com/detail/layered-code/loccgmbbilmanbbegkmaekakhhakeihh

Option 2: Developer Mode

Open Chrome Extensions Page:
- Navigate to chrome://extensions/
- Enable "Developer mode" in the top right corner
Load the Extension:
- Click "Load unpacked"
- Navigate to the chrome-extension folder in your layered-code directory
- Select the folder and click "Select"
Verify Installation:
- You should see "Layered Code Live Preview" in your extensions list
- The extension icon will appear in your Chrome toolbar

Usage:

Open your HTML file directly in Chrome (e.g., file:///Users/yourname/LayeredApps/myproject/index.html)
The extension will automatically detect file changes made through MCP
Your browser will refresh instantly when changes are saved

Features:

Automatic page refresh on file changes
Works with static HTML files
No configuration required - just install and use
Seamless integration with Claude Desktop MCP workflow

🔧 Optional: Custom Apps Directory

By default, Layered Code uses ~/LayeredApps as the directory for your applications. To use a custom directory:

For MCP (Claude Desktop): Add an env section to your configuration:

{
  "globalShortcut": "",
  "mcpServers": {
    "layered-code": {
      "command": "layered-code",
      "args": ["mcp_server"],
      "env": {
        "LAYERED_APPS_DIRECTORY": "~/MyCustomAppsFolder"
      }
    }
  }
}

For CLI usage: Set the LAYERED_APPS_DIRECTORY environment variable in your shell:

export LAYERED_APPS_DIRECTORY="~/MyCustomAppsFolder"
layered-code tool list_apps

🔒 Security

Layered Code maintains security when configuring custom app directories:

For security, paths are validated to ensure they're within the user's home directory
Relative paths are allowed and resolved relative to the user's home directory

🖥️ CLI Usage

Use layered-code directly from the command line:

# Start MCP server
layered-code mcp_server

# List apps
layered-code tool list_apps

# Get version information
layered-code version
layered-code -v
layered-code --version

# Get help and usage information
layered-code help
layered-code -h
layered-code --help

Available Commands:

mcp_server - Start the Model Context Protocol server for Claude Desktop integration
tool - Run various tools and utilities (use with subcommands like below)
- tool list_apps - List all available applications in the apps directory
- tool list_files - List files and directories within an application with optional metadata (max depth: 10,000 levels)
- tool search_text - Search for text patterns in files within an application directory using ripgrep
- tool read_file - Read the contents of a file within an application directory
- tool write_file - Write or create a file within an application directory
- tool edit_file - Edit a file by performing find-and-replace operations
version, -v, --version - Display the current version of layered-code
help, -h, --help - Show usage information and available commands

🔨 Building from Source

Prerequisites: Go 1.24+

# Clone and build
git clone https://github.com/layered-flow/layered-code.git
cd layered-code
go build -o layered-code ./cmd/layered_code

# Verify installation
layered-code

🧪 Running Tests

Run the test suite to ensure everything is working correctly:

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

🤝 Contributing

We're excited about the potential for community contributions! While Layered Code is currently maturing toward version 1.0, we're focusing on stabilizing core functionality and APIs. During this phase, we welcome your ideas and feedback through GitHub Issues, but won't be accepting pull requests to ensure we can move quickly and make necessary breaking changes.

Once we reach version 1.0 and the foundation is solid, we'll be thrilled to open up to community pull requests as well. We believe this focused approach will create a better experience for everyone in the long run.

Feel free to: