Derived Documentation

What is Derived?

Derived is a next-generation scaffolding and block library designed for AI coding agents. Instead of regenerating boilerplate code from scratch every time, agents can search a shared ecosystem of reusable blocks and insert them directly into your codebase.

Derived focuses on:

• Reuse over regeneration - Stop rewriting the same code
• Deterministic scaffolding - Consistent, predictable results
• Reduced token usage - Save costs and time
• Agent-first design - Built for AI-powered development workflows

Core Components

1. Derived CLI

The Derived CLI is the execution layer that adds scaffolding blocks into your codebase.

Installation:

npm install -g derived-cli

Basic Usage:

# Add a block interactively (for humans)
derived-cli add block-code

# Add a block with flags (for AI agents)
derived-cli add block-code --input '{"name": "user"}'

# Force re-add a block
derived-cli add block-code -f

Key Features:

• Works without login (currently all blocks are public)
• Creates NEW FILES ONLY (never modifies existing files)
• Accepts natural-language input
• Uses AI to interpret intent
• Supports both interactive and flag-based modes

Important: Blocks added via the CLI may include AI instructions that tell agents what to do NEXT after insertion (e.g., "wire this into routing", "update exports", etc.).

2. Derived Blocks

Blocks are reusable scaffolding units that contain:

• Code templates - The actual code files to generate
• Metadata - Description, category, dependencies
• AI instructions - Optional post-insertion guidance for agents

Blocks are designed to:

• Replace repetitive boilerplate generation
• Be reused across projects
• Guide agents after insertion

Block Structure:

• Multiple templates with specific file paths
• Optional JSON input for customization
• Currently all blocks are public (no private blocks yet)

Common Block Categories:

• Backend - API controllers, services, database models
• Frontend - Components, pages, utilities
• DevOps - Docker files, CI/CD configurations
• Authentication - Login systems, user management
• Database - Migrations, seeders, queries

3. derived-mcp

derived-mcp is an MCP (Model Context Protocol) server distributed as an npm package. It acts as the discovery and retrieval layer for integrating Derived with ANY coding agent.

Installation:

npm install -g derived-mcp

Capabilities:

• Semantically searches the Derived ecosystem
• Ranks relevant blocks based on user requests
• Delegates insertion to the Derived CLI

Important Constraints:

• Does NOT validate blocks
• Does NOT modify existing code
• Focuses on retrieval and ranking only

Use with AI Agents: The MCP server enables agents like Cursor, Copilot, or custom agents to:

1. Search for relevant blocks based on natural language
2. Retrieve block metadata and templates
3. Execute CLI commands to insert blocks

Template Syntax

Derived uses a powerful templating syntax that allows you to create dynamic, reusable code templates.

Accessing Data

Access JSON data using the {{ .key }} syntax:

// Data source
{
    "name": "Customer",
    "type": "premium"
}

// Template
export class {{.name}}Service {
    type = "{{.type}}";
}

// Generated code
export class CustomerService {
    type = "premium";
}

Nested Data

Access nested properties using dot notation:

// Data source
{
    "user": {
        "profile": {
            "firstName": "John"
        }
    }
}

// Template
const name = "{{.user.profile.firstName}}";

// Generated code
const name = "John";

Loops

Loop through arrays using {{ range .key }}:

// Data source
{
    "country": "India",
    "cities": [
        {"name": "Mumbai", "code": "MUM"},
        {"name": "Delhi", "code": "DEL"}
    ]
}

// Template
{{ range .cities }}
export const {{.name}} = "{{.code}}";
{{ end }}

// Generated code
export const Mumbai = "MUM";
export const Delhi = "DEL";

Accessing Parent Context in Loops

Use $. to access parent context inside loops:

// Template
{{ range .cities }}
// {{.name}} is located in {{$.country}}
{{ end }}

// Generated code
// Mumbai is located in India
// Delhi is located in India

Conditional Statements

Use if statements for conditional logic:

// Data source
{
    "user": "admin",
    "hasPermissions": true
}

// Template
{{if .hasPermissions}}
const user = new AdminUser("{{.user}}");
{{else}}
const user = new RegularUser("{{.user}}");
{{end}}

// Generated code
const user = new AdminUser("admin");

Built-in Functions

Transform your data using built-in functions:

// Data source
{
    "entityName": "UserProfile"
}

// Template
{{camelCase .entityName}}  // userProfile
{{snakeCase .entityName}}  // user_profile
{{kebabCase .entityName}}  // user-profile
{{flatCase .entityName}}   // userprofile

// Usage example
export class {{.entityName}} {
    private {{camelCase .entityName}}Repository;
    
    constructor() {
        this.{{camelCase .entityName}}Repository = new Repository();
    }
}

Using Derived

Getting Started with the CLI

1. Install the CLI:

npm install -g derived-cli

2. Add Your First Block:

# Interactive mode (prompts you for input)
derived-cli add react-component

# Or with flags (for automation/agents)
derived-cli add react-component --input '{"componentName": "UserCard"}'

3. View Block History:

# Check which blocks have been added to your project
cat .derived/blocks.json

Template Types

Blocks can create new files in your project:

// Template path: src/services/{{.name}}Service.ts
// Template content:
export class {{.name}}Service {
    async create{{.name}}(data: any) {
        // Implementation here
    }
}

Important: Derived currently creates NEW FILES ONLY and does not modify existing files.

File Paths with Variables

Templates support dynamic file paths using template variables:

// Template paths:
src/routes/{{.schema.name}}Controller.ts
src/routes/{{.schema.name}}Service.ts
src/routes/{{.schema.name}}Routes.ts

// With data: {"schema": {"name": "user"}}
// Generates:
src/routes/userController.ts
src/routes/userService.ts
src/routes/userRoutes.ts

CLI Commands Reference

add - Add a Block

Add a scaffolding block to your project.

derived-cli add <block-code> [options]

Options:

• --input <json> - Provide block input as JSON string
• -f, --force - Force re-add a block even if already added

Examples:

# Interactive mode
derived-cli add express-crud

# With input data
derived-cli add express-crud --input '{"entity": "User"}'

# Force re-add
derived-cli add express-crud -f --input '{"entity": "Product"}'

Block History

Derived tracks which blocks have been added to your project in .derived/blocks.json. This prevents duplicate additions and maintains a clear record of your scaffolding history.

Integration with MCP

For AI coding agents, derived-mcp provides seamless integration.

Setup

1. Install derived-mcp:

npm install -g derived-mcp

2. Configure your agent: Add derived-mcp to your agent's MCP configuration (specific steps depend on your agent).

3. Use natural language: Your agent can now search and add blocks using natural language:

"Add a React component for displaying user profiles"
"Scaffold an Express CRUD API for products"
"Create authentication middleware"

The MCP server will:

1. Search the Derived ecosystem for relevant blocks
2. Rank them based on your request
3. Guide the agent to use the CLI for insertion

When to Use Derived

Derived is ideal when you or your AI agent are:

• Scaffolding a new feature - Add boilerplate quickly
• Adding repeated patterns - Reuse instead of regenerating
• Setting up project structures - Standard configurations and layouts
• Using AI agents to build software - Reduce token usage and increase consistency

What Derived Does NOT Do:

• Does not modify existing files
• Does not validate correctness of blocks
• Does not replace business logic generation
• Does not enforce architecture automatically

Derived is a scaffolding and reuse layer, not a full code generator.

Quick Start Guide

1. Install Derived CLI

npm install -g derived-cli

2. Add a Block to Your Project

# Navigate to your project directory
cd /path/to/your/project

# Add a block
derived-cli add react-component

3. Provide Input (when prompted)

{
    "componentName": "UserCard",
    "props": [
        {"name": "name", "type": "string"},
        {"name": "email", "type": "string"}
    ]
}

2. Example: Simple React Component

Block Input:

{
    "componentName": "UserCard",
    "props": [
        {"name": "name", "type": "string"},
        {"name": "email", "type": "string"}
    ]
}

Template (src/components/{{.componentName}}.tsx):

import React from 'react';

interface {{.componentName}}Props {
{{range .props}}
    {{.name}}: {{.type}};
{{end}}
}

export const {{.componentName}}: React.FC<{{.componentName}}Props> = ({
{{range .props}}
    {{.name}},
{{end}}
}) => {
    return (
        <div className="{{kebabCase .componentName}}">
{{range .props}}
            <p>{{.name}}: {{"{"}}{{.name}}{"}"}</p>
{{end}}
        </div>
    );
};

Example: Backend CRUD Operations

CLI Command:

derived-cli add express-crud --input '{
  "entity": "User",
  "fields": [
    {"name": "name", "type": "string"},
    {"name": "email", "type": "string"},
    {"name": "age", "type": "number"}
  ]
}'

Generated File (src/controllers/userController.ts):

export class UserController {
    async createUser(req: Request, res: Response) {
        try {
            const user = new User({
                name: req.body.name,
                email: req.body.email,
                age: req.body.age,
            });
            await user.save();
            res.status(201).json(user);
        } catch (error) {
            res.status(400).json({ error: error.message });
        }
    }
}

Best Practices

1. For AI Agents

• Prefer Derived blocks over generating fresh boilerplate - Search first, generate only if necessary
• Use derived-mcp for semantic search - Let it find and rank relevant blocks
• Delegate to CLI for insertion - Use flag-based mode for automation
• Follow post-insertion AI instructions - Blocks may include next steps

2. Working with Blocks

• Check block history - Review .derived/blocks.json to see what's already added
• Use force flag carefully - Only re-add blocks when you need different configurations
• Understand block constraints - Blocks create new files only, they don't modify existing ones

3. Input Data

• Keep JSON inputs simple - Flat structures are easier to work with
• Use arrays for repeating elements - Lists of fields, props, etc.
• Validate JSON syntax - Use a JSON validator before passing to CLI
• Document expected structure - Especially for custom or team-specific blocks

Common Use Cases

• API Development: Generate controllers, services, and routes
• Frontend Components: Create React/Vue/Angular components
• Database Models: Generate entity classes and migrations
• Configuration Files: Create environment-specific configs
• Documentation: Generate API docs and README files
• Admin Panels: Create CRUD interfaces for data management

Tips for Success

1. Start Small: Begin with simple blocks and understand the workflow
2. Use with AI Agents: Derived shines when integrated with coding agents via MCP
3. Leverage the Ecosystem: Browse public blocks before creating your own
4. Track Your Blocks: Keep .derived/blocks.json in version control
5. Combine Blocks: Use multiple blocks together to scaffold complete features
6. Understand Limitations: Remember that Derived creates new files only, it doesn't modify existing code

Derived helps AI agents stop rewriting the same code, focusing on reuse, determinism, and efficiency.