AASWE - AI-Assisted Software Engineering

Rich codebase context for IDE LLMs through automatic analysis and TTL knowledge generation.

AASWE transforms your codebase into structured semantic knowledge (RDF/TTL format) that enhances your IDE's AI capabilities. Get better code suggestions, more accurate refactoring, and deeper insights by providing your LLM with comprehensive project context through the Model Context Protocol (MCP).

Quick Start

For Users (NPM Installation)

# Install and use
npm install -g @aaswe/codebase-ai
cd your-project
codebase-ai full-start

For Developers (Source Code)

# Clone and run from source
git clone https://github.com/AssahBismarkabah/AIDe.git
cd AIDe
npm install && npm run build
node dist/cli/index.js full-start --build

Visual Overview

Live Knowledge Graph Visualization - AASWE automatically generates comprehensive Neo4j graph databases showing your codebase structure. The example above shows a java codebase:

** Module Nodes**: Each directory/module represented as connected nodes
** Dependency Relationships**: Clear visualization of how modules depend on each other
** Entity Metrics**: Real class, method, and function counts displayed on nodes
** Architecture Patterns**: Visual detection of architectural layers and patterns
Interactive Exploration: Click and explore your codebase structure in real-time

Features

Semantic Knowledge Generation

TTL Files: Structured semantic knowledge in RDF/TTL format for each module
Real Entity Counts: Actual class, function, and dependency statistics
Module-Level Context: Comprehensive analysis of code structure and relationships
Business Context: Preserves developer annotations and domain knowledge

Multi-Language Code Analysis

12 Languages: TypeScript, JavaScript, Python, Java, Go, Rust, C++, C#, PHP, Ruby, Kotlin, Scala, Swift
Recursive Discovery: Finds and analyzes all source files throughout project tree
Concrete Information: Real class names, method signatures, dependencies, imports
Architectural Patterns: Detects common design patterns and code structures

Universal IDE Integration via MCP

Model Context Protocol: Works with any MCP-compatible IDE
Dual Transport: WebSocket and Stdio support for maximum compatibility
RooCode/Cline: Stdio transport for CLI-based IDEs
VS Code/Cursor: WebSocket transport for GUI IDEs
Real-time Updates: File watching and automatic context refresh

Flexible Deployment Options

Context-Only Mode: TTL files only (recommended for most users)
Full System Mode: Neo4j + MCP Server + Redis for advanced features
Docker Compose: Complete containerized deployment
Local Installation: NPM package for easy setup

System Requirements

Minimum (Context-Only Mode)

Node.js: 18.0.0+
Memory: 512MB RAM
Disk: 100MB free space

Recommended (Full System)

Node.js: 20.0.0+
Memory: 2GB RAM
Disk: 1GB free space
Docker: 20.0.0+ with Docker Compose V2 (for full system)
- Check with: docker compose version
- Should show: Docker Compose version v2.x.x

Installation & Setup

Global Installation

npm install -g @aaswe/codebase-ai

Project Initialization

# Navigate to your project
cd your-project

# Initialize AASWE
codebase-ai init

# For full system mode
codebase-ai init --mode full

Configuration

AASWE creates these files:

aaswe.config.js - Main configuration
.env.aaswe - Environment variables
.aaswe/ - Analysis cache and knowledge files

⚠️ Important: --build Flag Usage

When to Use --build Flag

The --build flag is only for developers working with source code:

# Source installation (cloned repository)
git clone https://github.com/AssahBismarkabah/AIDe.git
cd AIDe
node dist/cli/index.js full-start --build

When NOT to Use --build Flag

Never use --build with npm installations:

# This will fail with npm installations
npm install -g @aaswe/codebase-ai
codebase-ai full-start --build  # ← Will fail!

# Use without --build for npm installations
npm install -g @aaswe/codebase-ai
codebase-ai full-start  # ← Uses pre-built images

Prerequisites for Full System Mode

Before running codebase-ai full-start, ensure you have:

Docker Compose V2 Required

# Check if you have Docker Compose V2
docker compose version

# Should show: Docker Compose version v2.x.x
# If you see "command not found" or v1.x.x, please upgrade

Docker Engine Version

# Check Docker version (20.10+ recommended)
docker --version

⚠️ Important: The full-start --build command requires Docker Compose V2 (command: docker compose with space). Docker Compose V1 (docker-compose with hyphen) cannot access the NPM package's docker-compose.yml file and will not work with the global installation.

Quick Compatibility Check

# This should work without errors:
docker compose --help

# If you see "unknown command" or "command not found":
# You need to install Docker Compose V2 first!

Tip: The CLI will automatically check for Docker Compose availability and provide installation instructions if missing.

Usage

Basic Commands

Start the System

# Context-only mode (recommended)
codebase-ai start

# Full system mode
codebase-ai start --mode full --port 8000

# Complete system with all containers (Neo4j + MCP + Redis)
codebase-ai full-start


# With debug logging
codebase-ai start --debug

MCP Server Commands

# Start MCP server with stdio transport (for RooCode/Cline)
codebase-ai mcp --transport stdio

# Start MCP server with WebSocket transport (for VS Code/Cursor)
codebase-ai mcp --transport websocket --port 3001

# Start both transports (maximum compatibility)
codebase-ai mcp --transport both --port 3001

# With Neo4j integration
codebase-ai mcp --transport both --neo4j-uri bolt://localhost:7687 --neo4j-username neo4j --neo4j-password aaswe-password

# With debug logging
codebase-ai mcp --transport stdio --debug

Analyze Your Project

# Basic analysis
codebase-ai analyze

# Custom output directory
codebase-ai analyze --output ./knowledge

# Specific languages
codebase-ai analyze --languages typescript,python

Check Status

# Check if server is running
codebase-ai status

# Check specific port
codebase-ai status --port 3001

Docker Commands

# Start with Docker
codebase-ai docker up -d

# View logs
codebase-ai docker logs -f

# Stop services
codebase-ai docker down

IDE Configuration

AASWE provides dual-transport MCP support for maximum IDE compatibility:

RooCode / Cline (Stdio Transport)

Start AASWE System (in your project directory):

# Option 1: Full system with containers (npm installation)
codebase-ai full-start --project-path ./your-project

# Option 1b: Full system with containers (source installation only)
node dist/cli/index.js full-start --project-path ./your-project --build

# Option 2: Standalone MCP server (TTL files only)
codebase-ai mcp --transport stdio --ttl-directories ./your-project

Add to RooCode/Cline MCP Settings:

For NPM Installation (Recommended):

{
  "mcpServers": {
    "aaswe": {
      "command": "codebase-ai",
      "args": ["mcp", "--transport", "stdio", "--ttl-directories", "/path/to/your/project"]
    }
  }
}

For Source Installation (Developers):

{
  "mcpServers": {
    "aaswe": {
      "command": "node",
      "args": [
        "/path/to/aaswe/dist/cli/index.js",
        "mcp",
        "--transport",
        "stdio",
        "--ttl-directories",
        "/path/to/your/project"
      ]
    }
  }
}

VS Code with Continue (WebSocket)

Install the Continue extension
Start AASWE WebSocket Server:

node dist/cli/index.js mcp --transport websocket --port 3001

Add to your Continue config.json:

{
  "mcpServers": {
    "aaswe": {
      "command": "codebase-ai",
      "args": ["mcp", "--transport", "websocket", "--port", "3001"],
      "env": {}
    }
  }
}

Cursor (WebSocket)

Start AASWE WebSocket Server:

node dist/cli/index.js mcp --transport websocket --port 3001

Go to Settings → Features → Model Context Protocol
Add server:
- Name: AASWE
- Command: codebase-ai
- Args: ["mcp", "--transport", "websocket", "--port", "3001"]

Both Transports (Maximum Compatibility)

# Start both WebSocket and Stdio transports
node dist/cli/index.js mcp --transport both --port 3001

Other IDEs

WebSocket: Connect to ws://localhost:3001
Stdio: Use command-line MCP client with stdio transport

Project Structure

your-project/
├── aaswe.config.js          # AASWE configuration
├── .env.aaswe              # Environment variables
├── .aaswe/                 # AASWE data directory
│   ├── knowledge/          # Generated TTL files
│   ├── cache/              # Analysis cache
│   └── backups/            # Business context backups
└── knowledge/              # Custom output directory
    ├── src.module-knowledge.ttl
    ├── services.module-knowledge.ttl
    └── ...

Configuration

Basic Configuration (`aaswe.config.js`)

module.exports = {
  mode: 'context-only', // or 'full'
  server: {
    port: 3001,
    host: 'localhost'
  },
  context: {
    maxTokens: 8000,
    maxFiles: 10,
    relevanceThreshold: 0.3
  },
  ttl: {
    watchEnabled: true,
    watchDebounce: 1000
  }
};

Environment Variables (`.env.aaswe`)

# API Keys (optional)
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here

# Neo4j (full mode only)
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=aaswe-password

# Analysis settings
ANALYSIS_DEPTH=comprehensive
PRESERVE_BUSINESS_CONTEXT=true

🔧 Advanced Usage

Custom Analysis Patterns

// aaswe.config.js
module.exports = {
  analysis: {
    includePatterns: ['**/*.ts', '**/*.js', '**/*.py'],
    excludePatterns: ['**/test/**', '**/node_modules/**'],
    languages: ['typescript', 'javascript', 'python'],
    depth: 'comprehensive'
  }
};

Business Context Enhancement

# Add business context to generated TTL files
@prefix biz: <http://aaswe.org/business#> .

aide:UserService a aide:Class ;
    biz:businessDomain "User Management" ;
    biz:businessRule "Users must have unique email addresses" ;
    biz:businessProcess "User registration and authentication" .

Docker Customization

# docker-compose.override.yml
version: '3.8'
services:
  aaswe-server:
    environment:
      - CUSTOM_SETTING=value
    volumes:
      - ./custom-config:/app/config

Monitoring & Health Checks

Health Check Endpoint

curl http://localhost:3001/health

System Status

# Check all services
codebase-ai status

# Docker services
codebase-ai docker logs aaswe-server

Metrics (Full Mode)

Web Interface: http://localhost:3000
Neo4j Browser: http://localhost:7474
Metrics Endpoint: http://localhost:9090/metrics

Troubleshooting

Common Issues

"Command not found: aaswe"

# Reinstall globally
npm uninstall -g @aaswe/codebase-ai
npm install -g @aaswe/codebase-ai

# Or use npx
npx @aaswe/codebase-ai --version

"Port already in use"

# Use different port
aaswe start --port 3002

# Or kill existing process
lsof -ti:3001 | xargs kill -9

"TTL files not found"

# Re-analyze project
codebase-ai analyze --output ./knowledge

# Check permissions
ls -la ./knowledge/

"Neo4j connection failed"

# Check Neo4j status
docker-compose ps neo4j

# Restart Neo4j
docker-compose restart neo4j

# Start full system properly (npm installation)
codebase-ai full-start

# Or for source installation
node dist/cli/index.js full-start --build

"Docker Compose Not Available"

If you see unknown shorthand flag: 'd' in -d or similar Docker errors:

# Check if Docker Compose is installed
docker compose --help

# If command not found, install Docker Compose V2:

# Option 1: Install Docker Desktop (includes Compose V2)
# Download from: https://docs.docker.com/desktop/

# Option 2: Install Compose plugin (Linux)
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Option 3: Manual installation
# Follow: https://docs.docker.com/compose/install/

# Verify installation
docker compose version

"Docker Compose V1 Compatibility"

# Check your Docker Compose version
docker compose version  # V2 (preferred)
docker-compose --version  # V1 (legacy)

# If you have V1 only, you have two options:

# Option 1: Upgrade to Docker Compose V2 (RECOMMENDED)
# Follow: https://docs.docker.com/compose/install/

# Option 2: Clone the repository and use manual commands
git clone https://github.com/AssahBismarkabah/AIDe.git
cd AIDe
docker-compose up -d --build neo4j redis
# Then in another terminal (from your project directory):
codebase-ai start --mode full

"MCP Server Connection Issues"

# Test MCP stdio connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | codebase-ai mcp --transport stdio

# Check if MCP server is running
codebase-ai status --port 3001

# Restart with debug logging
codebase-ai mcp --transport both --debug

# For RooCode: Ensure correct path in MCP settings
ls -la /path/to/your/project/dist/cli/index.js

"TTL files showing zero counts"

# This was a known bug - now resolved!
# Re-analyze to get real entity counts
codebase-ai analyze --output ./knowledge

# Check if TTL files contain real data
grep -E "(classCount|functionCount|methodCount)" ./knowledge/*.ttl

Performance Optimization

Large Projects

# Exclude unnecessary files
codebase-ai analyze --exclude "**/node_modules/**,**/dist/**"

# Use incremental analysis
codebase-ai analyze --incremental

# Limit analysis depth
codebase-ai analyze --depth basic

Memory Issues

# Increase Node.js memory
export NODE_OPTIONS="--max-old-space-size=4096"
codebase-ai start

Architecture

Deployment Modes

Context-Only Mode

Full System Mode

Technology Stack

Backend: Node.js, TypeScript
Knowledge: RDF/TTL, SPARQL
Database: Neo4j (optional)
Protocol: Model Context Protocol (MCP)
Deployment: Docker, Docker Compose

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/AssahBismarkabah/AIDe.git
cd AIDe

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev

Running Tests

# All tests
npm test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

📚 Documentation

Installation Guide - Detailed setup instructions
API Documentation - MCP server API reference
Architecture Guide - System design and components
Development Guide - Contributing and development setup

Links

GitHub: https://github.com/AssahBismarkabah/AIDe
NPM Package: https://www.npmjs.com/package/@aaswe/codebase-ai
Issues: https://github.com/AssahBismarkabah/AIDe/issues
Discussions: https://github.com/AssahBismarkabah/AIDe/discussions

License

MIT License - see LICENSE file for details.

Acknowledgments

Model Context Protocol: For the universal IDE integration standard
Neo4j: For the powerful graph database
RDF/SPARQL: For semantic web standards
TypeScript: For type-safe development
Docker: For containerization and easy deployment

Transform your codebase into intelligent context for better AI-assisted development.

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github/workflows		.github/workflows
.specs		.specs
docs		docs
main/docs		main/docs
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.aaswe		.env.aaswe
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
aaswe.config.js		aaswe.config.js
docker-compose.local.yml		docker-compose.local.yml
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
test-analysis.js		test-analysis.js
tsconfig.json		tsconfig.json

License

ADORSYS-GIS/AIDe

Folders and files

Latest commit

History

Repository files navigation

AASWE - AI-Assisted Software Engineering

Quick Start

For Users (NPM Installation)

For Developers (Source Code)

Visual Overview

Features

Semantic Knowledge Generation

Multi-Language Code Analysis

Universal IDE Integration via MCP

Flexible Deployment Options

System Requirements

Minimum (Context-Only Mode)

Recommended (Full System)

Installation & Setup

Global Installation

Project Initialization

Configuration

⚠️ Important: --build Flag Usage

When to Use --build Flag

When NOT to Use --build Flag

Prerequisites for Full System Mode

Docker Compose V2 Required

Docker Engine Version

Quick Compatibility Check

Usage

Basic Commands

Start the System

MCP Server Commands

Analyze Your Project

Check Status

Docker Commands

IDE Configuration

RooCode / Cline (Stdio Transport)

VS Code with Continue (WebSocket)

Cursor (WebSocket)

Both Transports (Maximum Compatibility)

Other IDEs

Project Structure

Configuration

Basic Configuration (aaswe.config.js)

Environment Variables (.env.aaswe)

🔧 Advanced Usage

Custom Analysis Patterns

Business Context Enhancement

Docker Customization

Monitoring & Health Checks

Health Check Endpoint

System Status

Metrics (Full Mode)

Troubleshooting

Common Issues

"Command not found: aaswe"

"Port already in use"

"TTL files not found"

"Neo4j connection failed"

"Docker Compose Not Available"

"Docker Compose V1 Compatibility"

"MCP Server Connection Issues"

"TTL files showing zero counts"

Performance Optimization

Large Projects

Memory Issues

Architecture

Deployment Modes

Context-Only Mode

Full System Mode

Technology Stack

Contributing

Development Setup

Running Tests

📚 Documentation

Links

License

Acknowledgments

Basic Configuration (`aaswe.config.js`)

Environment Variables (`.env.aaswe`)

Packages