CxIDE/docs/DEVELOPER.md

CxIDE — Developer Guide

Getting Started

# Clone and enter project
git clone <repo-url> CxIDE && cd CxIDE

# Run first-time setup
./scripts/setup.sh

Setup validates your toolchain, installs git hooks, and builds the agent CLI.

Project Structure

CxIDE/
├── SwiftIDEApp.swift         # @main entry point
├── EngineFactory.swift       # Engine selection factory
├── SwiftCodeEngine.swift     # Full Swift execution engine
├── SandboxedSwiftEngine.swift # Safe interpreter
├── Core/                     # C++ analysis engine
│   ├── CodeEngine.hpp/cpp    # Tokenizer, metrics, analysis
│   ├── SwiftEngineWrapper.*  # ObjC++ bridge
│   ├── CodeEngine.swift      # CppEngineController facade
│   └── FileItem.swift        # File model
├── Agent/                    # Embedded MCP agent (56 tools)
│   ├── MCPServer.swift       # JSON-RPC server
│   ├── MCPTypes.swift        # Protocol types
│   ├── AgentConfig.swift     # Configuration
│   ├── AgentMemory.swift     # Session memory
│   └── Tools/                # 8 tool modules
├── Models/                   # Data models
├── Views/                    # SwiftUI views
├── ViewModels/               # View models
├── Services/                 # AgentService
├── CxSwiftAgent/             # Standalone SPM agent package
├── scripts/                  # Build & dev scripts
├── hooks/                    # Git hooks
└── docs/                     # Documentation

Daily Workflow

Build & Run

# Compile C++ engine + ObjC++ bridge
./scripts/build.sh

# Release build
./scripts/build.sh release

# Open in Xcode for SwiftUI development
open CxIDE.xcodeproj   # or create one if needed

Testing

# Run full test suite (C++ validation + agent tests + structure check)
./scripts/test.sh

# Agent tests only
cd CxSwiftAgent && swift test

# Lint check
./scripts/lint.sh

Clean Build

./scripts/clean.sh

Adding Features

Adding a new View

1. Create Views/YourView.swift
2. Add any new model types to Models/Models.swift
3. Wire into IDEContainerView.swift (sidebar or panel)
4. Add state to EditorViewModel.swift if needed

Adding an Agent Tool

1. Choose the appropriate module in Agent/Tools/ (or create a new one)
2. Add tool registration in the module's register() function:

server.registerTool(MCPToolDefinition(
    name: "your_tool_name",
    description: "What it does",
    inputSchema: ["type": "object", "properties": [...]],
    annotations: ToolAnnotations(readOnlyHint: true)
) { params in
    // Implementation
    return ["content": [["type": "text", "text": "result"]]]
})

3. If it's a new module, register it in Services/AgentService.swift:

YourModule.register(on: server, config: config, memory: memory)

4. Add the tool name to AgentService.toolCategories and optionally readOnlyTools
5. Add a routing keyword in AgentService.routeMessage() if applicable

Modifying the C++ Engine

1. Add declaration to Core/CodeEngine.hpp
2. Implement in Core/CodeEngine.cpp
3. Add ObjC wrapper method in Core/SwiftEngineWrapper.h and .mm
4. Add Swift facade method in Core/CodeEngine.swift (CppEngineController)
5. Rebuild: ./scripts/build.sh

Commit Conventions

This project uses Conventional Commits:

type(scope): description

Types:  feat, fix, refactor, docs, test, build, ci, chore, perf, style, agent
Scopes: core, agent, views, models, services, vm, engine, tools

Examples:

feat(agent): add workspace analysis tool
fix(core): handle nested block comments in tokenizer
refactor(views): extract agent chat into separate component
docs: update architecture diagram
test(agent): add integration tests for file operations
build: add release optimization flags

The commit-msg hook enforces this format automatically.

Git Hooks

Installed automatically by ./scripts/setup.sh or manually:

cp hooks/* .git/hooks/ && chmod +x .git/hooks/*

Hook	What It Does
pre-commit	Validates C++ syntax, scans for secrets and merge markers
commit-msg	Enforces conventional commit format
pre-push	Compiles C++ engine, runs agent tests, scans for sensitive data

Agent Commands

Available from the Command Palette (Cmd+Shift+P) or the Agent sidebar:

Command	Shortcut	Description
Agent: Explain Code	Cmd+Shift+E	Explain the current editor content
Agent: Review Code	Cmd+Shift+R	Review code for issues and improvements
Agent: Fix Issues	—	Auto-fix detected issues
Agent: Generate Tests	—	Generate unit tests for current code
Agent: Analyze Workspace	—	Full workspace analysis
Agent: Run Diagnostics	—	Lint, complexity, and health checks
Agent: Security Audit	—	Scan for security vulnerabilities
Agent: List Tools	—	Show all 56 available tools

Direct Tool Invocation

In the Agent chat panel, prefix with / to call a tool directly:

/file_list {"path": "."}
/git_status {}
/diag_complexity {"path": "Core/CodeEngine.cpp"}

Environment Variables (Agent)

Variable	Default	Description
CX_WORKSPACE	cwd	Workspace root path
CX_LOG_LEVEL	info	Logging: debug, info, warn, error
CX_PROFILE	development	Profile: development, staging, production
CX_SANDBOX	false	Restrict to read-only tools
CX_AUTH_TOKEN	—	API authentication token
CX_HOST	127.0.0.1	HTTP server bind address
CX_PORT	3001	HTTP server port

Troubleshooting

C++ bridge not linking: Ensure the bridging header Core/SwiftEngineWrapper.h is set in Xcode Build Settings → "Objective-C Bridging Header".

Agent tools not registering: Check Services/AgentService.swift initialize() — all 8 tool modules must be registered.

Swift execution fails: SwiftCodeEngine needs /usr/bin/swift — macOS only. On other platforms, the sandbox engine is used automatically.

Sandbox mode blocks writes: Toggle agentService.sandboxMode or unset CX_SANDBOX.