Linus

A terminal based, conversational AI coding partner. Batteries and sass fully included.

Features

• 🧭 You're the Navigator: Linus acts as your pair programmer. He proposes a plan, you discuss it, then give the final approval. No code gets written without your say-so.
• 📂 Complete Project Context: Reads your current codebase, directory structure, conversation history, and terminal logs to deeply understand every request.
• 🔋 Smart Context Filtering: Automatically respects .gitignore and supports custom .linignore patterns, ensuring Linus only focuses on the code that matters.
• 💻 Native Terminal Experience: Built from the ground up for the command line, with a focus on speed and a keyboard-driven workflow.
• 🛡️ Security Focused: Strictly uses embedded file read/write tools and curated external context (Google Search, URL reading). No support for external, declarative MCP servers, keeping your execution environment controlled and predictable.
• 🌐 Live Web Access: Grounded with up-to-the-minute search results. Just paste a URL, and it will read the content.
• 🪟 Seamless Tmux Integration: Automatically incorporates the content and history of relevant tmux panes into its context.
• 🔧 Per-Project Customization: Fine-tune behaviour and provide lasting instructions for each project using a simple .lin.md file.
• ⚡ Precision Code Generation: Leverages advanced prompt architecture and state management to deliver surgical, high-quality code updates while maintaining efficiency.

Architecture

See the docs/ARCHITECTURE.md file for a deep dive into Linus's architecture and design decisions.

Dependencies

• Python 3.11+
• Gemini
• uv
• just

Setup

git clone git@github.com:brentlintner/linus.git
cd linus
uv sync --no-dev
cp .env.example .env
open .env # Edit .env and set your API key and model (run `ai -m` with a valid key to see available models)
bin/ai -h

Usage

Start up a simple chat repl with no open files, just the project directory structure, terminal pane logs, and conversation history:

ai

Project File Access

Use the -f flag to enable read access for various files or directories.

ai -f .

Use the -w flag to enable file system write access. If not enabled, code will only be displayed in the chat, but not actually written to files.

ai -wf .

You can also list the files the model can access if -f is used with the -l flag. Helpful if you have a large project and want to see what files are available for the AI to read.

ai -lf .

Additionally, you can list the total token size of the files in your project with the -t flag to get an idea of how large the prompt will be:

ai -tf .

Ignoring Files

By default, Linus ignores certain files and directories that are commonly not useful for code generation, such as node_modules, .git, and build artifacts.

He also auto ignores anything in .gitignore.

You can also ignore files and directories by creating a .linignore file in your project root. This file supports glob patterns, similar to .gitignore.

Command Completion

You can reference files in your project by typing @ followed by a fuzzy search of the file name. For example, typing @README will show you a list of files that match README, and you can select one to reference its full path in your chat.

Project Specific Customization

You can create a .lin.md file in your project root to customize the AI's behaviour and context for that specific project. This file can include instructions, context, or any other information you want the AI to consider when interacting with your project.

Prompt Optimization

Currently there is no automatic prompt size optimization, so you need to be careful about the size of your project. If you find that the prompt is too large, use a more granular -f flag to limit the files the AI has open, and use a .linignore file or the -i flag to ignore specific files or directories.

Cleaning Up

To remove your project's conversation history, you can use the -c flag, or just remove the .lin.db file in your project root.

ai -c

Verbose Mode

To see more details about the AI's actions, such as searches performed, token usage, and more, you can enable verbose mode by adding the -v flag:

ai -vwf .

Development

just dev-setup # Install all dependencies including development dependencies
just dev # Start a development session with debug output and file access

License & Credits

Authors

• Brent Lintner
• Linus (the one doing the actual coding)

Battle-Tested At

Linus is used daily for production development at:

• StepStone Partners
• Forthright

License

This project is licensed under the Mozilla Public License 2.0 (MPL 2.0).

⚖️ Legal Disclaimer & Attribution

Linus is a non-commercial, open-source parody project.

• Not an Official Product: This tool is not affiliated with, sponsored by, or endorsed by Linus Torvalds or the Linux Foundation.

• Likeness & "The Meme": The branding—including the name "Linus" and any AI-generated imagery referencing the 2012 "Nvidia incident"—is used under fair use as a cultural tribute and parody. We use these symbols because Torvalds’ "Show me the code" philosophy is the gold standard for this AI’s behavior; we are not claiming to be him.

• Trademark Note: "Linux®" is a registered trademark of Linus Torvalds in the U.S. and other countries, managed by the Linux Foundation. This project does not use the Linux trademark for commercial purposes.

Essentially: This is a personal fan project designed to make you a better dev by coding with an AI personality based on one of the greatest, no-BS average joe programmers of the modern age. Don't sue us; we’re just vibe-coding over here.