CodeGuide

A comprehensive toolkit for AI-powered code guidance and project management. Includes both a CLI tool and a programmatic API for seamless integration into your development workflow.

Packages

🔧 @codeguide/cli - Command Line Interface

A powerful CLI tool for code guidance with full project management capabilities.

Features:

• Project creation and initialization
• Task management and tracking
• API key management
• Usage analytics and monitoring
• Repository analysis
• Interactive command-line interface

Installation:

npm install -g @codeguide/cli

📚 @codeguide/core - Programmatic API

The core package with TypeScript interfaces and services for integrating CodeGuide into your applications.

Features:

• Full TypeScript support with IntelliSense
• API key management (CRUD operations)
• Project management services
• Task management APIs
• Usage analytics
• Multiple authentication methods

Installation:

npm install @codeguide/core

Quick Start

CLI Usage

# Install CLI
npm install -g @codeguide/cli

# Authenticate
export CODEGUIDE_DATABASE_API_KEY="sk_your_key"

# Create a new project
codeguide init my-project

# View and manage tasks
codeguide task list
codeguide task update <task_id> --status in_progress
codeguide task update <task_id> "Progress notes"

Programmatic Usage

// Install core package
npm install @codeguide/core

import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide({
  baseUrl: 'https://api.codeguide.ai',
  databaseApiKey: 'sk_your_key'
})

// Create API key
const newKey = await codeguide.apiKeyEnhanced.createApiKey({
  name: 'My Application'
})

Documentation

| Package | Description | Link | |---------|-------------|------| | CLI | Command-line interface with full documentation | README | | Core | Programmatic API with TypeScript support | README |

Commands

Project Management

# Start a new project
codeguide start [prompt] [options]

# Initialize current directory
codeguide init

# Generate documentation
codeguide generate [options]

Task Management

# List tasks
codeguide task list [options]

# Start a task
codeguide task update <task_id> --status in_progress

# Update a task
codeguide task update <task_id> [options]

Authentication

# Interactive login
codeguide login

# Login with API key
codeguide login --api-key your-api-key

# Check health
codeguide health

# Check authentication status
codeguide auth status

Usage Management

# Check credit balance
codeguide usage balance

# View usage summary
codeguide usage summary

# Check authorization status
codeguide usage auth

CLI Options

Start Command

codeguide start [prompt] [options]

Options:
  -l, --language <language>    Programming language
  -c, --context <context>      Additional context
  -v, --verbose               Verbose output
  -o, --output <file>         Output file (default: README.md)
  --api-url <url>             API URL
  --api-key <key>             API key
  --current-codebase          Generate in current directory
  -h, --help                  Display help

Task Commands

codeguide task list [options]

Options:
  --status <status>           Filter by status (pending, in_progress, completed)
  --page <number>             Page number
  --page-size <number>        Page size

codeguide task update <task_id> [options]

Options:
  --status <status>           Update status
  --ai-result <result>        AI completion result
  --title <title>             Update title
  --description <description> Update description

Project Structure

When you create a new project with codeguide start, it generates:

my-project/
├── codeguide.json           # Project configuration
├── AGENTS.md               # AI agent guidelines
├── instructions.md         # Getting started guide
└── documentation/          # Generated documentation
    ├── project-outline.md
    ├── technical-specs.md
    └── implementation-plan.md

Configuration

Environment Variables

• CODEGUIDE_API_URL: API base URL (default: https://api.codeguide.dev)
• CODEGUIDE_API_KEY: API key for authentication

Authentication

The CLI supports multiple authentication methods:

1. Database API Key (highest priority): sk_... format
2. Legacy API Key (medium priority): Traditional API keys
3. Clerk JWT Token (lowest priority): JWT tokens

Authentication configuration is automatically saved locally for convenience.

Interactive Authentication

The CLI now supports interactive authentication setup:

# Interactive login with API key creation
codeguide login

# Direct API key authentication
codeguide login --api-key your-api-key

Development

Setup

# Clone repository
git clone https://github.com/CodeGuide-dev/codeguide.git
cd codeguide

# Install dependencies
npm install

# Build all packages
npm run build

# Link for local development
npm run dev:link

Available Scripts

# Build all packages
npm run build

# Build specific package
npm run build:core
npm run build:cli

# Run CLI in development mode
npm run dev

# Run tests
npm run test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Type checking
npm run typecheck

# Format code
npm run format

Project Structure

codeguide/
├── packages/
│   ├── core/              # Core package (@codeguide/core)
│   │   ├── dist/          # Built JavaScript files
│   │   ├── services/      # API services
│   │   ├── types.ts       # TypeScript types
│   │   └── api-service.ts # Main API service
│   └── cli/               # CLI package (@codeguide/cli)
│       ├── dist/          # Built JavaScript files
│       ├── commands.ts    # CLI commands
│       ├── utils/         # Utility functions
│       └── index.ts       # CLI entry point
├── package.json           # Root workspace configuration
└── README.md              # This file

API Usage

Programmatic Usage

import { CodeGuide } from '@codeguide/core'

const codeguide = new CodeGuide(
  {
    baseUrl: 'https://api.codeguide.dev',
    databaseApiKey: 'your-api-key',
  },
  {
    language: 'typescript',
    verbose: true,
  }
)

// Check health
const isHealthy = await codeguide.isHealthy()

// Generate project title
const title = await codeguide.generation.generateTitle({
  description: 'A React app with TypeScript',
})

// Generate project outline
const outline = await codeguide.generation.generateOutline({
  project_type: 'react',
  description: 'A React app with TypeScript',
  title: title.title,
})

Core Services

The core package provides access to all API services:

• Generation Service: Generate titles, outlines, and documents
• Projects Service: Create and manage projects
• Tasks Service: Task management and tracking
• Usage Service: Usage tracking and credit management
• Repository Service: Code analysis and insights

Examples

Create a React Project

codeguide start "Create a React app with TypeScript, Tailwind CSS, and routing" --language react

Generate Documentation for Existing Project

cd existing-project
codeguide init
codeguide generate --current-codebase

Check Usage and Credits

codeguide usage balance
codeguide usage summary --start-date 2024-01-01 --end-date 2024-12-31

Troubleshooting

Common Issues

1. Authentication Failed

   # Check your API key
   codeguide login --api-key your-api-key
   
   # Verify API health
   codeguide health

2. Permission Denied

   • Ensure your API key has sufficient permissions
   • Check your subscription status

3. Build Errors

   # Clean build
   npm run build
   
   # Check types
   npm run typecheck

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• API Documentation: API Docs

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run npm run dev:prepare to lint and typecheck
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

v0.0.11

• Bump version to 0.0.11
• Add --api-key flag to login command for non-interactive authentication
• Add interactive docs setup command with API key creation links
• Fix TypeScript error in cancellation funnel service

v0.0.10

• Enhanced task management system
• Added codespace service for development environments
• Improved error handling and type safety

v0.0.1

• Initial release
• Project creation with AI-generated documentation
• Task management system
• Authentication and usage tracking
• CLI and programmatic API interfaces