SIMON — Software Impact & Modeling Navigator

A local-first, CLI-driven engineering intelligence agent that analyzes code changes, detects workflow risks, generates design artifacts, and helps engineers understand impact before shipping.

Overview

SIMON is an AI-powered engineering assistant that serves as a centralized knowledge system and design aid for software teams. It ingests engineering artifacts (code, docs, APIs) and provides grounded answers, explanations, and structured engineering outputs such as READMEs and architecture diagrams.

Architecture

SIMON is built as a monorepo with the following packages:

• @simon-ai/core - SIMON Core API (Fastify server)
• @simon-ai/cli - Command-line interface
• @simon-ai/ui - React-based web UI
• @simon-ai/types - Shared TypeScript types

For detailed architecture documentation, see ARCHITECTURE.md.

Getting Started

Prerequisites

Option 1: Docker (Recommended)

• Docker >= 20.10.0
• Docker Compose >= 2.0.0

Option 2: Local Development

• Node.js >= 24.0.0 (LTS)
• npm >= 10.0.0

Note: Docker is the recommended approach for development. See DOCKER_DEVELOPMENT.md for Docker setup or LOCAL_DEVELOPMENT.md for local setup.

Docker Development (Recommended)

# Build and start development environment
docker-compose -f docker-compose.dev.yml up --build

# Or use npm script
npm run docker:dev

# Access services:
# - Core API: http://localhost:3000
# - UI Dev Server: http://localhost:5173

See DOCKER_DEVELOPMENT.md for complete Docker setup guide.

Local Development (Alternative)

# Install dependencies
npm install

# Build all packages
npm run build

# Set environment variables (create .env file)
# SIMON_REPO_PATH=/path/to/repo
# SIMON_LLM_PROVIDER=local  # Options: local, openai, anthropic
# SIMON_LLM_MODEL=glm-4.7-flash-claude-opus-4.5-high-reasoning-distill
# SIMON_LLM_BASE_URL=http://localhost:1234/v1
# SIMON_LLM_API_KEY=your-api-key  # Required for openai/anthropic

# Run development servers
npm run dev

See LOCAL_DEVELOPMENT.md for complete local setup guide.

For usage instructions, see USAGE.md.

Docker Production

# Build production image
docker build -t simon:latest .

# Run with docker-compose
docker-compose up -d

# Or use npm script
npm run docker:prod

Development

Docker is recommended for development, but local setup is also supported.

• Docker Setup: See DOCKER_DEVELOPMENT.md
• Local Setup: See LOCAL_DEVELOPMENT.md

Testing

Code coverage must be >= 80% (non-negotiable)

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests with coverage check (fails if < 80%)
npm run test:coverage:check

# Run tests in watch mode
npm run test:watch

Tests are automatically checked before commits via the pre-commit hook.

Quick Start (Docker)

# Start development environment
docker-compose -f docker-compose.dev.yml up --build

# Run commands inside container
docker-compose -f docker-compose.dev.yml exec simon-dev npm run build
docker-compose -f docker-compose.dev.yml exec simon-dev npm test

Quick Start (Local)

# Install and build
npm install
npm run build

# Run development servers
npm run dev

Documentation

Essential Guides

• ARCHITECTURE.md - System architecture and design
• USAGE.md - How to use SIMON (CLI, UI, API)
• DOCKER_DEVELOPMENT.md - Docker setup and development
• LOCAL_DEVELOPMENT.md - Local setup and development
• TESTING.md - How to run tests

Additional Documentation

• docs/LLM_PROVIDERS.md - LLM provider configuration guide

License

[To be determined]

Status

🚧 In Development - MVP implementation phase