CodeScribe

From Linear ticket to pull request, automated.

An AI-powered agent ecosystem that automates the entire development pipeline, from generating initial code drafts to creating fully-packaged pull requests.

The Problem • The Solution • How It Works • Quick Start • Tech Stack

---

The Problem: The "Cold Start" & The "Final Mile"

Every developer knows the loop. A new ticket lands. The first thirty minutes are a momentum-killing grind of context-switching, file-hunting, and boilerplate. Then, after hours of brilliant coding, you face the "final mile": another thirty minutes of writing commit messages, crafting PR descriptions, running quality checks, and updating tickets.

This friction at the beginning and end of every task is a massive drain on creativity and velocity.

The Solution: Your AI Apprentice

CodeScribe is a comprehensive agent ecosystem built to eliminate this friction entirely. We're not just another AI assistant; we are a proactive automation platform that handles the tedious work so developers can focus on what they do best: building.

• 💡 The Idea Engine: For Product Managers, CodeScribe takes a high-level feature request and uses a Vellum workflow to generate a preliminary code diff, providing a tangible starting point for engineering.
• 🚀 The Developer's Co-Pilot: For Developers, CodeScribe lives in the Warp terminal, providing a suite of commands to kickstart development and automate the entire PR submission process.
• 🤖 The Team's Reviewer: For the whole team, CodeScribe acts as a tireless agent inside Linear, responding to @mentions to perform automated code reviews.

---

A Day in the Life with CodeScribe

This is not just a tool; it's a completely new way to work.

1. The Kickstart: From Ticket to Code in Seconds

A developer is assigned a ticket COD-42. Instead of starting from scratch, they run one command.

codescribe apply COD-42

Instantly, the AI-generated starter code from our Vellum workflow is applied to their local files. The "cold start" problem is solved.

2. The Finish Line: From Code to PR in One Command

After the developer has applied their expertise and finished coding, they run the ultimate command.

codescribe pr

This single command triggers a powerful automation cascade:

• AI-Generated Commits: Analyzes changes and writes perfect, conventional commit messages.
• Automated PRs: Creates or updates a GitHub pull request with a rich, AI-generated description.
• Visual Documentation: For complex logic, it auto-generates Mermaid diagrams and embeds them in the PR.
• Built-in Scans: Performs quick code quality and security checks.
• Seamless Sync: Posts a final "Agent Action" back to the Linear ticket with the PR link.

The developer never leaves their terminal. The "final mile" is covered in seconds.

---

This experience taught us a critical lesson: a successful AI product isn't just about a clever prompt. It's about building a resilient, fault-tolerant system around the AI to manage its inherent unpredictability.

What's Next for CodeScribe

We're incredibly proud of what we built in a weekend, but we're just scratching the surface of what's possible. Our roadmap includes:

1. IDE Extension: A "one-click apply" and "one-click PR" button directly in VS Code, bringing the agent's power even closer to the developer's workflow.
2. Automated Test Generation: The agent will not only write the feature code but also generate corresponding unit test stubs to ensure code quality from the start.
3. Self-Improving Feedback Loop: Allow developers to approve or reject the AI's changes. This feedback will be used to fine-tune the AI model, making it smarter and more aligned with a specific team's coding style over time.
4. Interactive Patch Application: Instead of applying the entire diff at once, the agent will present individual "hunks" of code changes, allowing the developer to selectively accept or reject parts of the AI's suggestion.

---

Quick Start

Get up and running with CodeScribe in minutes.

1. Installation

Clone the repository and install dependencies.

git clone https://github.com/ManagementMO/CodeScribe.git
cd codescribe
npm install

# Set up your environment variable (BYO) for Gemini, Vellum, Linear, etc.
Example .env:
GITHUB_TOKEN=github_pat_...
LINEAR_AGENT_KEY=lagn_...
GEMINI_API_KEY=AIzaSy...
SUPABASE_URL=https://...supabase.co
SUPABASE_ANON_KEY=ey...

# Make the codescribe command globally available on your system.
npm link

# Basic Usage
Now you can use the CodeScribe agent from any git repository on your machine.

# Apply a preliminary diff from a Linear ticket
codescribe apply TICKET-ID

# Use it in warp! Press CTRL + R and search for the codescribe workflows to automate even further.

# Run the comprehensive PR creation/update workflow
codescribe pr

# See all available commands and options
codescribe --help 
---