AIDocs

AI-powered documentation toolkit

Automate your project documentation using agents that analyze your codebase, understand structure, and generate useful documentation.

Quick Start

Installation

npm install -g aestudio-aidocs

Init the AI doocs

aidocs init

Update your aidocs.json config file

{
  "OPENAI_API_KEY": ""
}

Usage

# Init the AI Docs
aidocs init             # It will create a .aidocs.json and append it to the .gitignore (if it exists)

# List available agents
aidocs list
aidocs list -t input    # Only input agents
aidocs list -t output   # Only output agents

# Run a single agent
aidocs <agent-name> [options]

# Pipe results between agents
aidocs pipe <output-agent> -i <input-agents...>
aidocs pipe <output-agent> -a  # Use all recent results

# Run a full pipeline
aidocs pipeline -i <input-agents...> -o <output-agent> -p <params>

Features

• Analyze codebase structure and dependencies
• Generate project summaries and documentation
• Keep docs up to date
• Turn Slack threads into documentation
• Query your codebase using natural language

Tools

Summary

Analyze project structure and generate a summary.

# Generate summary with default path (docs/summary.md)
aidocs summary

# Generate summary with custom path
aidocs summary -p "./some/directory"

# Generate summary with custom filename
aidocs summary -f "project-overview.md"

Save summary to docs:

# Using default path
aidocs pipeline -i summary -o update-docs

# Using custom filename
aidocs summary -f "custom-summary.md" | aidocs update-docs

ADRs

Uses the input request and the project files to generate an ADR file.

aidocs adr --title "A topic to write about"

Save the output to docs:

aidocs pipeline -i adr -o update-docs -p '{"title":"A topic to write about"}'

Chat

Interact with an agent that understands your codebase.

aidocs chat

Slack Thread Analyzer

Convert Slack threads to documentation.

aidocs slack-thread --thread <thread url>

Save the output to docs:

# Using the internal pipeline machinery
aidocs pipeline -i slack-thread -o update-docs -p '{"thread":"<thread url>"}'

Document Updater

Update docs with new content.

aidocs update-docs -i docs/ -c "New features"

Common Workflows

New Project

aidocs pipeline -i summary -o update-docs

Maintenance

aidocs summary
aidocs slack-thread <thread url>
aidocs pipeline -i summary -o update-docs

Team Knowledge

aidocs chat -f meeting-notes.md
aidocs slack-thread <thread url>
aidocs update-docs --target team-handbook/

Configuration

export OPENAI_API_KEY="your-key"
export SLACK_BOT_TOKEN="your-slack-token"  # optional

Requirements

• Node.js 22+
• OpenAI API key
• Optional: Slack token

Scripts

{
  "scripts": {
    "docs:analyze": "aidocs summary",
    "docs:update": "aidocs update-docs",
    "docs:full": "aidocs pipeline -i summary -o update-docs"
  }
}

Developing Agents

Create a class that extends GenericAgent in src/agents/input or output.

Template

import { GenericAgent } from '../generic-agent';

export default class MyAgent extends GenericAgent {
    constructor() {
        super({
            name: 'my-agent',
            description: 'What this agent does',
            type: 'input',
            options: [
                { flags: '-o, --option <value>', description: 'Some option' }
            ]
        });
    }

    async run(input: any) {
        return {
            type: 'ResultType',
            tags: ['tag1'],
            body: 'Result content'
        };
    }
}

License

MIT — see LICENSE

3. Options Definition

   options: [
       {
           flags: '-s, --short <value>', // Short and long form
           description: 'Option description',
           defaultValue: 'default' // Optional
       }
   ]

4. Run Method

   • Implements the agent's main functionality
   • Returns an AgentResult object:

     {
         type: string;      // Result type
         tags: string[];    // Categorization tags
         body: string;      // Main content
         metadata?: any;    // Optional additional data
     }

Best Practices

1. Error Handling

   • Use try-catch blocks in the run method
   • Provide meaningful error messages
   • Handle missing or invalid options

2. Input Validation

   • Validate required options
   • Check input types and formats
   • Provide default values when appropriate

3. Documentation

   • Write clear descriptions
   • Document all options
   • Include usage examples in help text

4. Testing

   • Test with various inputs
   • Verify error handling
   • Check option combinations

Contributing

1. Create a new agent class
2. Place it in the appropriate directory (input or output)
3. Implement required methods
4. Add tests
5. Update documentation

Testing

AIDocS uses Vitest as its testing framework with comprehensive unit and integration tests.

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run tests in watch mode
pnpm test -- --watch

For detailed testing guidelines, best practices, and examples, see the Testing Guide.

Made by AE Studio — Report Issues