Related Pages

Related topics: Installation Guide, System Architecture Overview

Introduction to AIDOCS

Overview

AIDOCS is an intelligent development system that provides AI coding agents with persistent memory, indexed retrieval, and orchestration capabilities. The platform enables AI agents to resume work efficiently instead of rediscovering repository context on every session. Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx

Purpose and Scope

AIDOCS addresses a fundamental challenge in AI-assisted development: context loss between sessions. When an AI coding agent completes a task or reconnects after a break, it traditionally must re-analyze the entire codebase to understand the project structure, recent changes, and development context. AIDOCS eliminates this inefficiency by maintaining persistent context that survives across sessions.

The system provides:

• Persistent Memory: Store and retrieve development context across agent sessions
• Indexed Retrieval: Fast lookup of relevant code, documentation, and project artifacts
• Orchestration: Coordinate multiple AI agents and their activities
• Security Guards: Built-in prompt injection detection and content filtering
• RBAC: Role-Based Access Control for multi-tenant environments

Architecture Overview

graph TD
    subgraph "AIDOCS Core"
        A[AI Coding Agent] --> B[MCP Server]
        B --> C[Memory System]
        B --> D[Index Engine]
        B --> E[Session Manager]
    end
    
    subgraph "Dashboard Layer"
        C --> F[CastleShell Dashboard]
        D --> F
        E --> F
        F --> G[OverviewPage]
        F --> H[ExecutionPage]
        F --> I[ConductorPage]
        F --> J[RBACPage]
    end
    
    subgraph "Security Layer"
        B --> K[output_guard.py]
        K --> L[Prompt Injection Detection]
        K --> M[Sensitive Content Filtering]
    end
    
    subgraph "External Integrations"
        N[MCP Registry] --> B
        B --> O[Claude.ai]
        B --> P[OpenAI API]
    end

Core Components

MCP Server (Model Context Protocol)

The AIDOCS MCP server acts as the central communication hub between AI agents and the AIDOCS backend. It handles tool routing, session management, and context retrieval.

Key Tools Provided:

Sources: mcp/README.md

Memory System

The memory system provides persistent storage for agent context:

graph LR
    A[Capture Event] --> B[memory_capture]
    B --> C[Memory Index]
    C --> D[memory_search]
    D --> E[Relevant Context]
    E --> F[Agent Context]

Memory Operations:

• memory_read: Retrieve stored memory entries
• memory_capture: Store new context from agent activities
• memory_search: Search across stored memories using natural language

Session Management

Sessions enable agents to resume work without context loss:

stateDiagram-v2
    [*] --> List: ai_session list
    List --> Create: ai_session create
    Create --> Connect: ai_session connect
    Connect --> Update: ai_session update
    Connect --> Resume: ai_session resume
    Update --> Release: ai_session release
    Resume --> Release
    Release --> [*]

Sessions maintain:

• Current status and goal
• Owner information
• Context budget (token estimates, journal entries)
• Recent execution history

Sources: apps/aidocs-dashboard/src/OverviewPage.tsx

Execution Tracking (Conductor)

The Conductor system tracks all tool calls and agent actions:

Sources: apps/aidocs-dashboard/src/ConductorPage.tsx, apps/aidocs-dashboard/src/ExecutionPage.tsx

Security Layer (output_guard.py)

AIDOCS includes robust security features to protect against prompt injection attacks:

Prompt Injection Patterns Detected:

Sensitive Content Patterns:

Sources: mcp/server/aidocs_mcp/output_guard.py

RBAC (Role-Based Access Control)

AIDOCS implements comprehensive role-based access control:

Key Features:

• Permission management with descriptions
• Escalation paths for elevated privileges
• Sticky escalations for persistent elevated access
• Session/task-scoped permission grants

Escalation Fields:

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

Dashboard Interface (CastleShell)

The AIDOCS Dashboard provides a web-based interface for monitoring and managing the system:

graph TD
    subgraph "CastleShell Components"
        A[CastleShell] --> B[Navigation]
        A --> C[StatusBar]
        A --> D[ContextRail]
        A --> E[TopStrip]
    end
    
    subgraph "Dashboard Pages"
        B --> O[OverviewPage]
        B --> P[ExecutionPage]
        B --> Q[ConductorPage]
        B --> R[RBACPage]
        B --> S[SkillsPage]
        B --> T[MonitoringPage]
        B --> U[RegistryPage]
        B --> V[TomlConfigsPage]
    end
    
    subgraph "Navigation Counts"
        C --> W[CastleNavCounts]
        W --> X[executions]
        W --> Y[sessions]
        W --> Z[escalations]
    end

CastleShell Props:

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

Setup and Installation

Initial Setup Wizard

The setup wizard guides users through project configuration:

graph LR
    A[Welcome] --> B[Project Selection]
    B --> C[Environment Check]
    C --> D[Host Configuration]
    D --> E[Configure]
    E --> F[Done]

Setup Steps:

1. Welcome: Introduction and feature overview
2. Project Selection: Choose project folder path
3. Environment Check: Verify Node.js and other dependencies
4. Host Configuration: Configure Claude.ai, OpenAI API access
5. Configure: Set up MCP, hooks, and project structure
6. Done: Confirmation of successful setup

Setup Wizard Features:

• Progress indicator showing current step
• Environment detection with status checks
• Host authentication status display
• Automatic installation option for missing tools
• Sign-in buttons for external services

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx

Environment Detection

The setup wizard detects:

MCP Registry Integration

AIDOCS supports discovering and installing MCP servers from a registry:

• Search functionality for MCP servers
• Install commands extraction
• Transport and command information display
• Website URL tracking

Sources: apps/aidocs-dashboard/src/RegistryPage.tsx

Workflow Patterns

Agent Workflow with AIDOCS

graph TD
    A[Start Task] --> B[ai_session create]
    B --> C[Define Goal]
    C --> D[ai_investigate]
    D --> E[ai_find / ai_trace]
    E --> F[ai_get_symbol_info]
    F --> G[Edit Code]
    G --> H[memory_capture]
    H --> I[ai_session update]
    I --> J{More Work?}
    J -->|Yes| E
    J -->|No| K[ai_task complete]
    K --> L[ai_session release]
    L --> M[End]

Code Editing Workflow

Recommended sequence for code modifications:

1. ai_get_lines — Read file content
2. ai_get_symbol_info(kind="signature"|"constructor") — Confirm target signatures
3. ai_edit_lines or ai_batch_edit — Apply changes
4. ai_task_complete — Mark task complete

Important: Do not mix different edit methods within the same task.

Investigation Workflow

For understanding unfamiliar code:

1. session_resume_bundle — Get project/session/skills/plan overview
2. action_surface_current_session_bundle — Identify likely next tools
3. ai_find(query, mode="symbols") — Locate relevant symbols
4. ai_get_symbol_snippet — Retrieve code snippets
5. ai_bundle(concept, mode="subsystem") — Get subsystem context

Sources: mcp/server/aidocs_mcp/data/opencode_plugin.js

Context Budget Management

Sessions track context budget usage:

Compaction: When context budget is running low, use the compact function to reduce token usage while preserving critical context.

Sources: apps/aidocs-dashboard/src/OverviewPage.tsx

Monitoring and Analytics

Execution Monitoring

Track agent activities across dimensions:

• By Event Kind: Categorize by tool type or action
• By Source: Track which agent or integration triggered events
• Recent Execution: View recent events with timestamps

Lane Management

Lanes provide execution isolation and context grouping:

• Events can be tagged with lane_id
• Related events are grouped together
• Status tracking (applied, refused, blocked)

Sources: apps/aidocs-dashboard/src/MonitoringPage.tsx, apps/aidocs-dashboard/src/LaneDetailPanel.tsx

Skills System

AIDOCS supports dynamic skill registration:

Sources: apps/aidocs-dashboard/src/SkillsPage.tsx

TOML Configuration

AIDOCS uses TOML for project and system configuration:

• Configuration document browsing by category
• Syntax-highlighted editor with save functionality
• Support for multiple TOML files per category

Sources: apps/aidocs-dashboard/src/TomlConfigsPage.tsx

Command Line Interface

Basic Commands

pip install aidocs-mcp
aidocs --version
aidocs-mcp   # start MCP server

Summary

AIDOCS provides a comprehensive platform for enhancing AI coding agents with persistent memory and intelligent context management. Its modular architecture includes:

• MCP Server: Central communication hub with 20+ specialized tools
• Memory System: Persistent storage and retrieval of development context
• Session Management: Seamless task resumption across agent sessions
• Security Layer: Prompt injection detection and sensitive content filtering
• RBAC: Fine-grained access control for enterprise environments
• Dashboard: Web-based monitoring and management interface

By integrating AIDOCS into AI-assisted development workflows, teams can significantly reduce the time agents spend re-establishing context, leading to faster development cycles and more consistent code quality.

Related Pages

Related topics: Introduction to AIDOCS, MCP Server Architecture

Installation Guide

AIDOCS is an AI-powered documentation and coding assistant platform that provides persistent memory, indexed retrieval, and orchestration for AI coding agents. This guide covers all installation methods, prerequisites, and configuration steps required to deploy AIDOCS in your development environment.

Prerequisites

Before installing AIDOCS, ensure your system meets the following requirements.

System Requirements

Supported AI Host Platforms

AIDOCS integrates with multiple AI coding assistants. The installation process detects available platforms.

Sources: SetupWizardPage.tsx:42-56

Installation Methods

AIDOCS supports multiple installation methods across different platforms.

Automated Installation

#### macOS and Linux

Use the shell installer script for POSIX-compliant systems:

curl -fsSL https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.sh | bash

The script performs the following operations:

1. Checks for required dependencies (Node.js, Python)
2. Creates necessary directory structure
3. Installs the AIDOCS CLI globally
4. Sets up MCP server configurations
5. Initializes the project workspace

Sources: core/scripts/install.sh

#### Windows

For Windows systems, use PowerShell:

irm https://raw.githubusercontent.com/cristian1991/AIDOCS/main/core/scripts/install.ps1 | iex

The PowerShell installer:

1. Validates PowerShell version (5.1+ required)
2. Installs dependencies via winget or chocolatey
3. Configures Windows-specific paths
4. Registers AIDOCS in the system PATH

Sources: core/scripts/install.ps1

Manual Installation

For custom deployments, install the CLI directly:

# Clone the repository
git clone https://github.com/cristian1991/AIDOCS.git
cd AIDOCS

# Install Python dependencies
pip install -e .

# Install Node.js dependencies
cd apps/aidocs-dashboard
npm install
npm run build

Setup Wizard

The first time you launch AIDOCS, a setup wizard guides you through the configuration process.

Workflow Overview

graph TD
    A[Welcome] --> B[Project Selection]
    B --> C[Prerequisites Check]
    C --> D[AI Host Configuration]
    D --> E[Configuring]
    E --> F[Done]
    
    C -->|Missing dependencies| G[Install Required Tools]
    G --> C
    
    D -->|Not authenticated| H[Sign In Required]
    H --> D

Step 1: Welcome

The welcome screen introduces AIDOCS capabilities:

AIDOCS gives your AI coding agents persistent memory, indexed retrieval, and orchestration — so they resume work instead of rediscovering your repo every time.

Sources: SetupWizardPage.tsx:25-31

Step 2: Project Selection

Specify the project folder where AIDOCS will operate:

<input
  type="text"
  value={projectPath}
  onChange={(e) => setProjectPath(e.target.value)}
  placeholder="Project folder path (or leave empty for current directory)"
/>

Sources: SetupWizardPage.tsx:50-55

Step 3: Prerequisites Check

The installer validates the presence of required tools:

Detection results display with status indicators:

For hosts requiring authentication:

<button onClick={() => {
  const url = h.name.includes("Claude") 
    ? "https://claude.ai" 
    : "https://platform.openai.com/api-keys";
  invoke("open_url", { url });
}}>Sign in</button>

Sources: SetupWizardPage.tsx:58-72

Step 4: Configuration

The installer configures MCP servers, hooks, and project structure:

{step === "configure" && (
  <div className="setup-content">
    <h2>Configuring</h2>
    <p>Setting up MCP, hooks, and project structure...</p>
    <div className="setup-spinner" />
  </div>
)}

Sources: SetupWizardPage.tsx:95-102

Step 5: Completion

Upon successful installation, the wizard displays:

Sources: SetupWizardPage.tsx:104-130

MCP Server Installation

AIDOCS supports Model Context Protocol (MCP) servers for extended functionality.

Server Registry

The dashboard includes a searchable registry of MCP servers:

<div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(320px, 1fr))", gap: "12px" }}>
  {results.map((server: RegistrySearchResult) => (
    // Server card rendering
  ))}
</div>

Sources: RegistryPage.tsx:25-28

Installing MCP Servers

Each server in the registry provides installation commands:

const installText = typeof firstCmd === "string" 
  ? firstCmd 
  : String((firstCmd as Record<string, string>).command ?? "");

Sources: RegistryPage.tsx:30-36

CLI Commands

The AIDOCS CLI provides command-line access to installation and management functions.

Primary Commands

Sources: mcp/server/aidocs_mcp/cli.py

Post-Installation Steps

After successful installation:

1. Open your project in your preferred IDE
2. Start a new agent session
3. Type /aidocs to begin

<div className="setup-next-steps">
  <h3>Next Steps</h3>
  <ol>
    <li>Open <strong>{projectPath || "your project"}</strong> in your IDE</li>
    <li>Start a new agent session</li>
    <li>Type <code>/aidocs</code> to begin</li>
  </ol>
</div>

Sources: SetupWizardPage.tsx:131-139

Dashboard Access

After installation, access the AIDOCS dashboard:

# Start the dashboard server
aidocs start

# Or open the dashboard directly
open http://localhost:3000

The dashboard is served from apps/aidocs-dashboard/ and provides:

• Overview: Session status, context budget, recent execution
• Registry: Browse and install MCP servers
• RBAC: Manage roles and permissions
• Execution: View tool call history
• Settings: Configure project options

Sources: apps/aidocs-dashboard/index.html

Troubleshooting

Common Issues

Verification

Confirm successful installation:

# Check AIDOCS version
aidocs --version

# Verify MCP connection
aidocs status

# Test configuration
aidocs config --validate

Upgrade Instructions

To upgrade AIDOCS to the latest version:

# Update via npm (if installed globally)
npm update -g aidocs

# Or use the built-in update command
aidocs update

After upgrading, run the setup wizard again to apply configuration changes:

aidocs setup --wizard

Uninstallation

To remove AIDOCS from a project:

# Remove AIDOCS files (keeps data)
aidocs uninstall

# Complete removal including data
aidocs uninstall --clean

This removes:

• .aidocs/ directory
• MCP configurations
• Hook registrations

Global CLI tools remain installed unless explicitly removed with npm uninstall -g aidocs.

Related Pages

Related topics: MCP Server Architecture, Dashboard Architecture, Memory System

System Architecture Overview

AIDOCS is a persistent memory and orchestration framework designed for AI coding agents. It provides indexed retrieval, session persistence, and policy-based control to enable AI agents to resume work efficiently without repeatedly rediscovering repository context. The system consists of a frontend dashboard application and a backend MCP (Model Context Protocol) server that communicates with AI coding agents.

Core Architecture Layers

AIDOCS operates through three primary architectural layers that work together to provide persistent context and control for AI agents.

Layer 1: MCP Server (`mcp/server/`)

The MCP server acts as the bridge between AI coding agents and the AIDOCS persistent storage system. It exposes tools and resources that agents can invoke during their sessions. The server handles context retrieval, session management, and policy enforcement through a standardized MCP interface.

The server provides several categories of tools including context management tools (ai_find, ai_get_symbol_snippet, ai_bundle), session tools (session_resume_bundle, action_surface_current_session_bundle), and investigation tools (ai_investigate). These tools enable agents to query indexed project knowledge, retrieve symbol information, and understand codebase structure.

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx Sources: mcp/server/aidocs_mcp/data/opencode_plugin.js

Layer 2: Dashboard Application (`apps/aidocs-dashboard/`)

The dashboard is a React-based web application that provides a visual interface for managing AIDOCS configuration, monitoring agent sessions, and administering security policies. The dashboard communicates with the MCP server through IPC (Inter-Process Communication) to retrieve and display session data.

The dashboard uses a modular component architecture built around the CastleShell wrapper, which provides consistent navigation, status indicators, and layout structure across all pages.

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

Layer 3: Persistent Storage and Indexing

AIDOCS maintains indexed knowledge of the project codebase, session state, and configuration policies. This indexing enables fast retrieval of relevant context when agents resume sessions or need to understand unfamiliar parts of the codebase.

Dashboard Component Architecture

The AIDOCS dashboard is structured as a single-page application with multiple views accessible through a navigation sidebar. Each view addresses a specific aspect of agent management and monitoring.

graph TD
    A[CastleShell] --> B[OverviewPage]
    A --> C[LivePage]
    A --> D[ConductorPage]
    A --> E[ExecutionPage]
    A --> F[RBACPage]
    A --> G[SettingsPage]
    A --> H[RegistryPage]
    A --> I[CommandPalette]
    
    B --> J[Snapshot Data]
    C --> K[Real-time Events]
    D --> L[Tool Routing]
    E --> M[Event Details]
    
    N[MCP Server] --> J
    N --> K
    N --> L
    N --> M

CastleShell — Main Application Wrapper

The CastleShell component serves as the root layout container for the entire dashboard. It manages navigation state, renders the sidebar, and displays the status bar showing connection status and project information.

Key Properties:

The status bar component within CastleShell indicates MCP connection state with a color-coded indicator (green for connected, red for disconnected) and displays the current session ID and active layer.

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

SetupWizardPage — Initial Configuration

The SetupWizardPage guides users through initial AIDOCS setup with a multi-step wizard interface. It handles project selection, dependency detection, MCP configuration, and hook registration.

Setup Steps Flow:

graph LR
    A[welcome] --> B[project]
    B --> C[detection]
    C --> D[configure]
    D --> E[done]
    
    A -->|Get Started| B
    B -->|Select Folder| C
    C -->|Dependencies OK| D
    D -->|Configuration Complete| E

The wizard validates system requirements including Node.js presence and AI platform authentication status (Claude, OpenAI). It can detect missing components and offer installation options directly within the interface.

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx

Session and Execution Monitoring

OverviewPage — Session Snapshot

The OverviewPage displays a consolidated snapshot of the current session including session metadata, capability usage statistics, and recent execution events. It provides at-a-glance monitoring of agent activity through a dashboard-style layout with panels for different data categories.

The page renders execution data in a tabular format showing capability names, action kinds, and timestamps for recent events. This allows operators to quickly assess agent behavior without drilling into detailed logs.

Sources: apps/aidocs-dashboard/src/OverviewPage.tsx

LivePage — Real-time Event Stream

The LivePage provides a real-time view of agent execution events with support for lane-based isolation and policy enforcement. It displays a scrollable event feed with status indicators and allows operators to approve or reject escalated permission requests.

LivePage Features:

The control panel on the right side of the page contains pending approvals with approve/reject buttons, quick action buttons for lane management, and lane detail expanders showing related events.

Sources: apps/aidocs-dashboard/src/LivePage.tsx

ExecutionPage — Detailed Event Analysis

The ExecutionPage provides deep-dive analysis of individual execution events. It displays full payload data, result summaries, and audit information for each recorded event. The page supports filtering and searching through execution history to locate specific agent actions.

LaneDetailPanel — Lane Event Context

The LaneDetailPanel component renders detailed information about specific execution lanes including related events, lane status, and execution history. Events are displayed with timestamps and status indicators that reflect whether actions were allowed, refused, or blocked.

Lane events show a color-coded status pill: green for applied or allowed, red for refused or blocked, and muted gray for other states.

Sources: apps/aidocs-dashboard/src/LaneDetailPanel.tsx

Policy Management

BashPolicyPanel — Shell Command Control

The BashPolicyPanel provides a visual interface for managing shell command execution policies. It displays a summary of allow/deny/bubble counts and allows filtering by policy type.

Policy Controls:

Each policy entry shows the effective counts for allow, deny, and bubble policies, along with the active layer where modifications were made and the default fallback policy.

Sources: apps/aidocs-dashboard/src/BashPolicyPanel.tsx

RBACPage — Role-Based Access Control

The RBACPage manages permissions, escalations, and custom policy configurations. It provides three tabbed views:

1. Policies Tab — Lists configured policies with their states (system/custom)
2. Permissions Tab — Shows available permission definitions
3. Escalations Tab — Displays pending or active permission escalations

The escalations table tracks requesters, requested permissions, session/task context, sticky status, and expiration timestamps.

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

MCP Server Integration

RegistryPage — MCP Server Discovery

The RegistryPage enables browsing and installing MCP servers from a remote registry. It supports searching for servers by name and displays installation commands, transport types, and website URLs for each available server.

Server Card Information:

Sources: apps/aidocs-dashboard/src/RegistryPage.tsx

ConductorPage — Tool Routing Configuration

The ConductorPage manages the conductor tool routing system, which controls how different AI backends (Claude, Codex, OpenCode) are used for various tasks. It displays recent tool calls with routing audit information and allows configuration of routing rules.

Conductor Configuration Options:

The page shows a diff viewer for edit operations, displaying old and new content side-by-side for easy comparison of changes made by the agent.

Sources: apps/aidocs-dashboard/src/ConductorPage.tsx

User Interface Components

CommandPalette — Quick Action Interface

The CommandPalette provides keyboard-driven access to common actions. It supports fuzzy search, keyboard navigation (arrow keys), execution (Enter), and quick filtering (Tab).

Keyboard Shortcuts:

The palette displays commands with status indicators showing whether they are allowed, denied, or require escalation.

Sources: apps/aidocs-dashboard/src/CommandPalette.tsx

SettingDetailPanel — Configuration Editor

The SettingDetailPanel displays detailed information about individual configuration entries including current values, origins, and layer assignments. It supports editing configuration values directly within the panel.

The panel includes a per-leaf origin view that shows which layers contributed to each configuration value, useful for understanding inheritance and override behavior in multi-layered configurations.

Sources: apps/aidocs-dashboard/src/SettingDetailPanel.tsx

Data Flow Architecture

graph TD
    subgraph Agents["AI Coding Agents"]
        Claude[Claude AI]
        Codex[Codex]
        OpenCode[OpenCode]
    end
    
    subgraph MCP["MCP Protocol Layer"]
        Tools[MCP Tools]
        Resources[MCP Resources]
        Notifications[Notifications]
    end
    
    subgraph Server["AIDOCS Backend"]
        Context[Context Engine]
        Index[Indexing Service]
        Policy[Policy Engine]
        Session[Session Manager]
    end
    
    subgraph Dashboard["Dashboard Frontend"]
        UI[React Components]
        IPC[IPC Bridge]
    end
    
    Claude -->|MCP| Tools
    Codex -->|MCP| Tools
    OpenCode -->|MCP| Tools
    
    Tools --> Context
    Context --> Index
    Index --> Policy
    Policy --> Session
    
    Session -->|Events| Dashboard
    UI -->|Config| Session
    IPC -->|Status| UI

Security Architecture

AIDOCS implements a multi-layered security model through the following mechanisms:

Permission Escalation: Agents can request elevated permissions for specific operations. These requests appear in the LivePage approval queue for operator review before execution proceeds.

Policy Layers: Configuration policies are organized into layers with inheritance. The SettingDetailPanel shows which layer contributed each configuration value, enabling audit and rollback.

Bash Command Policies: Shell execution is controlled through allow/deny/bubble policies. The BashPolicyPanel provides visibility into these rules and supports runtime modification.

Connection Verification: The status bar in CastleShell continuously monitors MCP connection status. Loss of connection triggers visual indicators and can be configured to halt agent execution.

Summary

The AIDOCS architecture provides a complete framework for persistent AI agent context management. The MCP server layer exposes tools for agents to query indexed knowledge and manage sessions. The dashboard provides comprehensive monitoring, configuration, and policy management capabilities. Together, these components enable AI coding agents to maintain context across sessions, operate within defined security boundaries, and provide operators with full visibility into agent activities.

Related Pages

Related topics: System Architecture Overview, Conductor & Orchestration, Security & Access Control

MCP Server Architecture

The AIDOCS MCP Server is a Python-based Model Context Protocol implementation that provides persistent memory, indexed retrieval, and orchestration capabilities for AI coding agents. It acts as an intermediary layer between AI coding assistants (like Claude Code or OpenCode) and project-specific context, enabling agents to maintain memory across sessions and resume work without re-discovering repository structures.

Core Architecture Overview

The MCP Server follows a modular architecture with distinct layers for tool management, security enforcement, and runtime orchestration.

graph TD
    subgraph "MCP Server Core"
        MS[mcp_server.py<br/>FastMCP Entry Point]
        SH[service_hub.py<br/>Service Hub]
    end
    
    subgraph "Tool Layer"
        TD[tool_discovery.py<br/>Tool Discovery]
        CE[server_code_edit_tools.py<br/>Edit Tools]
        CT[server_code_tools.py<br/>Code Tools]
    end
    
    subgraph "Security Layer"
        GATE[Gate Architecture<br/>6-Level Cascade]
    end
    
    subgraph "Runtime Services"
        RS[runtime_service.py<br/>Runtime Service]
        REG[mcp_registry.py<br/>Registry]
    end
    
    subgraph "External Integrations"
        CC[Claude Hook]
        OC[OpenCode Plugin]
    end
    
    MS --> SH
    SH --> TD
    SH --> CE
    SH --> CT
    SH --> RS
    MS --> REG
    CC --> MS
    OC --> MS

Sources: mcp/README.md

Server Entry Point

The mcp_server.py file serves as the primary entry point for the MCP server, initializing FastMCP and registering all available tools and resources.

Server Initialization

The server follows this initialization sequence:

1. Configuration Loading - Loads aidocs.toml from the project root
2. Service Hub Initialization - Establishes the central service coordinator
3. Tool Registration - Discovers and registers all available MCP tools
4. Registry Setup - Configures the MCP server registry for host integrations
5. Security Gate Bootstrap - Initializes the gate architecture

Sources: mcp/server/aidocs_mcp/mcp_server.py

Service Hub

The service_hub.py module acts as the central coordinator for all MCP services, providing a unified interface for tool execution, state management, and service discovery.

Hub Components

Managed Mode System

The Service Hub maintains a managed mode state that controls whether the MCP server operates in supervised or unsupervised mode.

managed = hub.managed_mode.get_mode(project_root)
if managed.get("active"):
    # Enforce gate architecture
    # Block raw file tools
    # Route through workflow system

Sources: mcp/server/aidocs_mcp/service_hub.py Sources: mcp/server/aidocs_mcp/server_code_edit_tools.py

Tool Discovery

The tool_discovery.py module implements dynamic tool discovery, enabling the MCP server to expose capabilities based on runtime context and project configuration.

Discovery Process

graph LR
    A[Project Root] --> B[Scan aidocs.toml]
    B --> C[Check .MEMORY/ Structure]
    C --> D[Validate Configuration]
    D --> E[Register Available Tools]
    E --> F[Expose via MCP Protocol]

Available Tool Categories

Sources: mcp/server/aidocs_mcp/tool_discovery.py

Code Analysis Tools

The code analysis tools provide AI agents with capabilities to navigate, understand, and investigate codebases.

Symbol Information Modes

The ai_get_symbol_info tool supports multiple query modes for different levels of symbol detail:

Sources: mcp/server/aidocs_mcp/server_code_tools.py

Investigation Patterns

The ai_investigate tool provides guided navigation with depth and focus parameters:

ai_investigate(concept, depth=..., focus=...)
# depth: exploration depth
# focus: symbol-ranked, favors types/classes/structs

Investigation alternatives:

• Known symbol name → ai_find(name, mode="symbols")
• Concept/type search → ai_investigate(concept, depth=..., focus=...)
• Architecture mapping → ai_bundle(path, mode="file"|"subsystem")

Gate Architecture

The security layer implements a 6-level cascade gate system that controls tool execution based on context and permissions.

Gate Levels

Sources: mcp/README.md

Gate Flow

graph TD
    A[Tool Request] --> B{Level 1: Managed Mode?}
    B -->|Unmanaged| C[Execute Tool]
    B -->|Managed| D{Level 2: Infrastructure?}
    D -->|No| E{Level 3: Sensitive Files?}
    D -->|Yes| X[Block + Log]
    E -->|No| F{Level 4: Memory Path?}
    E -->|Yes| X
    F -->|Check| G{Level 5: Read Gate?}
    G -->|No| H{Level 6: Edit Gate?}
    G -->|Yes| C
    H -->|Valid| C
    H -->|Invalid| X

Configuration Settings

Security gates can be configured via the dashboard:

Sources: apps/aidocs-dashboard/src/dashboardModals.tsx

Runtime Service

The runtime_service.py module manages session lifecycle, task orchestration, and state persistence.

Session Management

result = self.task_begin(
    project_root=project_root,
    session_id=session_id,
    goal=None,
    state=state,
    upcoming=upcoming,
    partial_goals=partial_goals,
    end_goal=end_goal,
    blockers=blockers,
    relevant_files=effective_relevant_files,
    relevant_commands=relevant_commands,
    relevant_snippets=relevant_snippets,
    session_facts=session_facts,
    constraints=constraints,
    include_code_bundle=include_code_bundle,
    include_tests=include_tests,
)

Sources: mcp/server/aidocs_mcp/runtime_service.py

State Tracking

The runtime service maintains:

• Session State - Current session identifier and metadata
• Task State - Active tasks, goals, and blockers
• Relevant Files - Files relevant to current task
• Relevant Commands - Commands needed for task completion
• Relevant Snippets - Code snippets for reference
• Session Facts - Accumulated knowledge about the session

Summary-Only Updates

When summary_only=True, the runtime service tracks which fields were updated:

updated_fields: list[str] = []
if state is not None:
    updated_fields.append("state")
if upcoming is not None:
    updated_fields.append("upcoming")
# ... additional field tracking

MCP Registry

The mcp_registry.py module provides registry functionality for MCP server discovery and management.

Registry Capabilities

• Server Discovery - Find available MCP servers in the system
• Transport Detection - Identify server transport protocols (stdio, SSE, etc.)
• Command Extraction - Parse install commands for server setup
• Server Management - Track installed and available servers

Registry UI Components

The dashboard displays registered servers with:

{srv.name} · {srv.transport} · {srv.command}

Search results show installation commands and website URLs for discovered servers.

Sources: mcp/server/aidocs_mcp/mcp_registry.py Sources: apps/aidocs-dashboard/src/RegistryPage.tsx

Host Integrations

The MCP server supports multiple AI coding assistant hosts through platform-specific integrations.

Claude Code Integration

The Claude hook (claude_hook.py) provides:

• Prompt injection with action directives
• Interaction text rendering
• Workflow summary compilation
• Tool preamble generation

_ACTION_DIRECTIVES = {
    "write_code": '`ai_create_file` → `ai_get_lines` (read) → `ai_edit_lines` or `ai_batch_edit` (write) → `task_complete`',
    "trace": '`ai_find(query, mode="references")` → `ai_trace(query, mode="field_flow"|"css_class"|"api_to_ui")`',
    "understand": '`session_resume_bundle` → `action_surface_current_session_bundle` → `ai_find(query, mode="symbols")` → `ai_get_symbol_snippet`',
}

OpenCode Integration

The OpenCode plugin (opencode_plugin.js) provides:

• Startup state detection
• Project initialization checks
• Execution prompt building
• Interaction text handling

Sources: mcp/server/aidocs_mcp/claude_hook.py Sources: mcp/server/aidocs_mcp/data/opencode_plugin.js

Memory Model

The MCP server maintains a hierarchical memory structure within project directories:

/.MEMORY/
  .aidocs/index.aidocs     # Session-start router
  sessions/                # Session-specific state
  skills/                  # Skill definitions
  plans/                   # Task plans

Memory Path Gate Rules

Edit Tool Sequencing

Sequential line-based edits to the same file can corrupt line numbers. The MCP server enforces:

1. Single-file line edits trigger a rejection if the file was already edited this turn
2. Batch alternatives (ai_batch_edit, ai_str_replace, ai_batch_str_replace) handle ordering internally
3. Line-independent matching bypasses the sequential edit check

def _check_turn_edited(project_root, path, tool_name):
    """Return rejection if file already edited this turn"""
    managed = hub.managed_mode.get_mode(project_root)
    if not managed.get("active"):
        return None
    # Check session_id and file edit history

Sources: mcp/server/aidocs_mcp/server_code_edit_tools.py

Installation and Setup

Package Installation

pip install aidocs-mcp              # from PyPI
pip install aidocs-mcp[dev]         # with pytest
pip install aidocs-mcp[ast]         # with tree-sitter for JS/TS AST parsing

Setup Command

aidocs setup                  # Configures MCP, hooks, project init
aidocs doctor                 # Verify the install

Setup Wizard

The dashboard includes a setup wizard (SetupWizardPage.tsx) that guides users through:

1. Welcome - Introduction to AIDOCS capabilities
2. Project Selection - Choose project folder
3. Configuring - MCP, hooks, and project structure setup
4. Done - Confirmation with checklist

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx Sources: README.md

Dashboard Status Indicators

The CastleShell UI component displays MCP connection status:

<span className={mcpConnected ? "text-castle-allow" : "text-castle-deny"}>
    <span className={mcpConnected ? "bg-castle-allow" : "bg-castle-deny"} />
    {mcpConnected ? "MCP connected" : "MCP disconnected"}
</span>

Status Bar Components

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

Related Pages

Related topics: System Architecture Overview, Conductor & Orchestration

Dashboard Architecture

The AIDOCS Dashboard is a Tauri-based desktop application that provides a comprehensive user interface for monitoring, managing, and configuring the AIDOCS AI coding assistant infrastructure. It serves as the central control plane for all AIDOCS operations, from initial project setup to ongoing session monitoring and security configuration.

Overview

The dashboard functions as a bridge between the user and the underlying MCP (Model Context Protocol) server infrastructure. It enables users to visualize project state, manage AI backends, configure security policies, and monitor token usage across sessions. The architecture follows a clean separation between the Rust-based Tauri backend and the React/TypeScript frontend, providing native desktop performance while maintaining rapid development iteration cycles.

The dashboard is designed to work in conjunction with the aidocs-mcp Python package, which runs as a separate MCP server process. The dashboard communicates with this server via IPC commands to retrieve runtime state and push configuration changes. This decoupled design allows the MCP server to operate independently of the dashboard GUI, enabling headless operation in CI/CD environments or remote servers.

Technology Stack

Frontend Layer

The frontend is built with React 18 and TypeScript, providing type-safe component development and modern hooks-based state management. Vite serves as the build tool and development server, offering fast hot module replacement during development and optimized production builds.

Sources: apps/aidocs-dashboard/index.html:1-10

Backend Layer

The Tauri backend is implemented in Rust, providing native system integration capabilities including window management, file system access, and process spawning. The backend exposes a command API that the React frontend invokes via Tauri's invoke mechanism.

Sources: README_INSTALL.md

Architecture Components

Component Hierarchy

graph TD
    A[Tauri Backend<br/>main.rs] --> B[React App<br/>App.tsx]
    B --> C[CastleShell<br/>Navigation Framework]
    C --> D[OverviewPage<br/>Project Overview]
    C --> E[RegistryPage<br/>MCP Server Registry]
    C --> F[ConductorPage<br/>Backend Routing]
    C --> G[RBACPage<br/>Access Control]
    C --> H[TomlConfigsPage<br/>TOML Editor]
    C --> I[UsagePage<br/>Token Analytics]
    C --> J[SetupWizardPage<br/>Initial Setup]
    C --> K[dashboardModals<br/>Confirmation Dialogs]
    
    L[StatusBar<br/>MCP Status] -.-> C
    M[ContextRail<br/>Sidebar Info] -.-> C
    N[CommandPalette] -.-> C

CastleShell Navigation Framework

The CastleShell component serves as the primary layout container, providing consistent navigation, status indication, and context management across all dashboard pages. It implements a tab-based navigation system with optional managed mode indicators.

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

#### Navigation Types

type NavKey = "overview" | "registry" | "conductor" | "rbac" | 
              "configs" | "usage" | "wizard";

#### Shell Props Interface

Status Bar

The status bar component provides real-time connection status and contextual information at the bottom of the application window. It displays MCP connection state with visual indicators and supports tooltip-based detailed status views.

Sources: apps/aidocs-dashboard/src/CastleShell.tsx:32-54

type CastleStatusBarProps = {
  mcpConnected: boolean;
  projectName?: string;
  sessionId?: string;
  activeLayer?: string;
  saveState?: string;
};

Dashboard Pages

Overview Page

The Overview page provides a snapshot of the current project state, including recent execution events, active sessions, and capability utilization. It renders a runtime snapshot retrieved from the MCP server via the dashboard API.

Sources: apps/aidocs-dashboard/src/OverviewPage.tsx

graph LR
    A[MCP Server] -->|Runtime Snapshot| B[OverviewPage]
    B --> C[Project Info Panel]
    B --> D[Recent Execution Table]
    B --> E[Capability Stats]

Registry Page

The Registry page enables browsing and searching the MCP server registry. Users can view installed servers, search for available servers by name, and initiate installations directly from the interface.

Sources: apps/aidocs-dashboard/src/RegistryPage.tsx

#### Registry Search Result Structure

interface RegistrySearchResult {
  name: string;
  install_commands?: Array<{
    command?: string;
    type?: string;
  }>;
  website_url?: string;
}

Conductor Page

The Conductor page manages backend routing configuration, allowing users to select between different AI backends (Claude, Codex, OpenCode) and configure per-backend model settings. It provides a visual representation of the routing lanes and their blocked/run states.

Sources: apps/aidocs-dashboard/src/ConductorPage.tsx

#### Conductor Configuration Model

interface ConductorConfig {
  backend: "claude" | "codex" | "opencode";
  models: {
    claude: string;
    codex: string;
    opencode: string;
  };
  lanes: ConductorLane[];
}

RBAC Page

The Role-Based Access Control page displays and manages permission grants, showing which sessions and tasks have been granted specific capabilities. It supports both sticky (persistent) and once (single-use) grant types with expiration tracking.

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

#### RBAC Entry Display

TOML Configuration Page

The TOML Configuration page provides a visual editor for AIDOCS TOML documents, organized by category. Users can view and manage configuration entries for Action Tokens, Action Hooks, and Language Descriptors.

Sources: apps/aidocs-dashboard/src/TomlConfigsPage.tsx

#### Configuration Categories

Usage Page

The Usage page visualizes token consumption across sessions, providing charts for input/output token ratios, session breakdowns, and tool-specific usage. It supports both bar and pie chart modes for different visualization preferences.

Sources: apps/aidocs-dashboard/src/dashboardCharts.tsx

#### Usage Data Model

interface TokenEstimates {
  tokens_in: number;
  tokens_out: number;
  tokens_in_calls?: number;
  tokens_out_calls?: number;
}

interface SessionBreakdown {
  session_id: string;
  total: number;
  events: number;
}

Setup Wizard

The Setup Wizard guides users through initial AIDOCS configuration with a multi-step flow. It handles project path selection, environment detection, and host authentication verification.

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx

#### Wizard Steps

graph LR
    A[welcome] --> B[project]
    B --> C[environment]
    C --> D[configure]
    D --> E[done]
    
    A -->|Get Started| B
    B -->|Configure| D
    E -->|Open Dashboard| F[Dashboard]

#### Setup Step Configuration

#### Environment Detection

The wizard detects available AI hosts and their authentication status:

interface HostDetection {
  name: string;
  found: boolean;
  authenticated: boolean;
  path?: string;
  installable?: boolean;
}

Supported hosts include Claude and OpenAI platforms, with sign-in buttons linking to respective authentication pages.

Modal Components

Security-sensitive operations require explicit user confirmation through modal dialogs. The dashboard provides dedicated confirmation modals for dangerous configuration changes.

Sources: apps/aidocs-dashboard/src/dashboardModals.tsx

#### Protected Settings

#### Loading Overlay

The LoadingOverlay component displays during snapshot refresh operations:

export function LoadingOverlay() {
  return (
    <div className="app-overlay" role="status" aria-live="polite">
      <div className="app-overlay-panel">
        <div className="overlay-spinner" />
        <strong>Loading runtime snapshot</strong>
        <span>Refreshing project, session, and settings state.</span>
      </div>
    </div>
  );
}

MCP Integration

The dashboard communicates with the AIDOCS MCP server through Tauri's IPC mechanism. The MCP server exposes tools for project management, session control, memory operations, and code analysis.

Core MCP Tools

Sources: mcp/README.md

Configuration Schema

The MCP server maintains configuration entries with support for various scopes and security classifications:

Sources: mcp/server/aidocs_mcp/config_schema.py

#### Security-Sensitive Settings

"dev.dev_mode": _setting(
    type="boolean",
    default=False,
    description="[T0 DASHBOARD-ONLY] Unlocks AIDOCS infrastructure source editing.",
    security_sensitive=True,
    dashboard_only=True,
    scope=["project"],
)

#### Tool Output Configuration

Build and Deployment

Development Mode

cd apps/aidocs-dashboard
npm install
npm run tauri dev

Production Build

npm run tauri build

The build process compiles the Rust backend and bundles the React frontend into a native executable.

Launch Scripts

Sources: README_INSTALL.md

Data Flow

sequenceDiagram
    participant User
    participant Dashboard as React UI
    participant Tauri as Tauri Backend
    participant MCP as MCP Server
    participant Project as Project Files
    
    User->>Dashboard: Navigate to page
    Dashboard->>Tauri: invoke("command", args)
    Tauri->>MCP: IPC / Tool Calls
    MCP->>Project: File System Operations
    Project-->>MCP: State / Config
    MCP-->>Tauri: Response
    Tauri-->>Dashboard: Serialized Data
    Dashboard-->>User: Rendered UI

Security Architecture

The dashboard implements several security measures:

1. T0 Dashboard-Only Settings: Certain configuration changes are restricted to the dashboard and cannot be modified by agents through NLP or tool calls.

1. Confirmation Modals: Security-sensitive operations require explicit user confirmation before execution.

1. Output Guard: The MCP server includes output filtering to detect and redact sensitive content patterns.

Sources: mcp/server/aidocs_mcp/output_guard.py

#### Sensitive Content Patterns

Design System

The dashboard uses the "Castle" design system with a dark theme and muted accent colors:

The design system is implemented via CSS custom properties, enabling consistent theming across all components.

Related Pages

Related topics: System Architecture Overview, Indexing & Retrieval System

Memory System

Overview

The AIDOCS Memory System provides persistent memory infrastructure for AI coding agents, enabling them to resume work across sessions without rediscovering repositories from scratch. The system organizes agent-generated knowledge into structured directories, validates memory file placement, detects stale content, and surfaces relevant memories during task execution.

Memory is stored in a .MEMORY directory at the project root, containing structured subdirectories for sessions, archived work, rules, standards, lessons, and roadmaps.

Architecture

graph TD
    subgraph "Memory Storage Layer"
        MEM[.MEMORY/]
        SESS[.MEMORY/sessions/]
        ARCH[.MEMORY/archive/]
        RULES[.MEMORY/rules/]
        STD[.MEMORY/standards/]
        LESS[.MEMORY/lessons/]
        ROAD[.MEMORY/roadmaps/]
    end
    
    subgraph "MCP Tools"
        MS[memory_store.py]
        SS[session_store.py]
        MD[memory_discovery.py]
        MF[memory_surfacer.py]
    end
    
    subgraph "Validation & Scanning"
        RS[runtime_service.py<br>memory_validator]
        SF[stale_finder]
        GP[pattern_scanner]
    end
    
    MEM --> SESS
    MEM --> ARCH
    MEM --> RULES
    MEM --> STD
    MEM --> LESS
    MEM --> ROAD
    
    SESS --> MS
    ARCH --> SS
    MS --> MD
    MD --> MF
    RS --> GP

Directory Structure

The Memory System enforces a specific directory structure to maintain organized, retrievable knowledge:

Sources: runtime_service.py:24-28

Memory File Naming Rules

The system enforces strict placement rules for memory files. These rules ensure consistent organization and enable reliable retrieval.

File Location Rules

Sources: runtime_service.py:47-67

Validation Logic

# For session files (SESSION.md, CONTEXT.md, TODO.md, NOTES.md)
ok = (
    (len(parts) == 3 and parts[0] == "sessions")
    or (len(parts) == 4 and parts[:2] == ("archive", "sessions"))
)

# For PLAN.md
ok = (
    (len(parts) == 4 and parts[0] == "sessions" and parts[2] == "plans")
    or (len(parts) == 5 and parts[:2] == ("archive", "sessions") and parts[3] == "plans")
)

Sources: runtime_service.py:58-67

Header Pattern Detection

The system scans memory files for header patterns that indicate the type of content and its organization. These patterns help categorize and prioritize memory retrieval.

G2 Patterns (Work-in-Progress Headers)

Files with these header patterns indicate ongoing investigation or active work:

g2_pattern = re.compile(
    r"^#+\s+(investigating|reading|trying|exploring|debugging|"
    r"checking|figuring|attempting|wip|todo:|notes?:)\b",
    re.IGNORECASE,
)

G3 Patterns (Planning Headers)

Files with these headers indicate structured planning or backlog items:

g3_pattern = re.compile(
    r"^#+\s+(plan|phase\s*\d|step\s*\d|steps|tasks|backlog|"
    r"roadmap|milestone)\b",
    re.IGNORECASE,
)

Skipped Directories

Certain directories are excluded from pattern validation as they are expected to contain these patterns:

Sources: runtime_service.py:29-35

Memory Validation API

`memory_structure_checker`

Validates the entire memory directory structure for compliance with naming and placement rules.

Parameters:

Returns:

{
    "ok": bool,
    "memory_root": str,
    "violations": [
        {
            "path": str,
            "name": str,
            "expected_location": str
        }
    ],
    "count": int,
    "error": Optional[str]
}

Error States:

Sources: runtime_service.py:12-21

Stale Memory Detection

`memory_stale_finder`

Identifies memory files that have not been modified in a configurable time period. This helps maintain memory freshness and prevents outdated information from being surfaced.

Parameters:

Rationale:

"Memory drifts: rules written months ago for a now-dead workflow are worse than no rules at all."

Sources: runtime_service.py:106-108

Memory Surfacing

The memory_surfacer module provides retrieval capabilities for surfacing relevant memories based on context. It consumes NLP-processed data to match current task context with stored memories.

Key Responsibilities

• Match query context against stored memory content
• Rank memories by relevance
• Filter memories by type, age, and source
• Handle deduplication across sessions

# Conceptual flow
user_query → context_extraction → memory_search → relevance_ranking → filtered_results

Sources: memory_surfacer.py

Memory Discovery

The discovery module (memory_discovery.py) provides mechanisms to locate and index memory files across the project.

Discovery Capabilities

• Recursive traversal of .MEMORY directory tree
• Filtering by memory type (sessions, rules, standards, lessons)
• Metadata extraction from memory file headers
• Cross-reference identification between memories

Session Store

Session storage maintains the state of agent sessions across the memory hierarchy.

Session File Types

Sources: session_store.py

Security Considerations

The Memory System integrates with the security guard infrastructure to protect against prompt injection and sensitive data leakage.

Pattern Scanning Integration

Memory files are scanned for:

• Prompt injection patterns (role hijack, instruction injection, delimiter escape)
• Sensitive content (env file patterns, SSH config)
• Capability declarations (file operations, command execution, database access)

See Security Gates for detailed pattern definitions.

Workflow

graph LR
    A[Agent Session Start] --> B[Create/Load Session]
    B --> C[Memory Discovery]
    C --> D[Relevant Memories Surfaced]
    D --> E[Agent Work]
    E --> F[Update Memory Files]
    F --> G[Structure Validation]
    G --> H[Archive or Keep Active]
    H --> I[Session End]

Configuration

Memory Root Location

Default: .MEMORY (relative to project root)

Validation Strictness

The system performs validation on:

• File naming conventions
• Directory placement
• Path segment counts
• Header pattern compliance

Staleness Threshold

Default: 90 days Configurable via stale_after_days parameter

Related Components

Related Pages

Related topics: MCP Server Architecture, Security & Access Control, Dashboard Architecture

Conductor & Orchestration

The Conductor & Orchestration system is the central coordination layer in AIDOCS, providing persistent, long-lived agent orchestration across coding sessions. Rather than spawning isolated one-off agent calls, the Conductor acts as a supervisory intelligence that plans, delegates, monitors, and resolves conflicts among multiple lane-based worker agents.

Overview

The Conductor orchestrates AI coding work by:

• Maintaining persistent memory across sessions
• Creating and managing execution lanes (isolated task pipelines)
• Routing tasks to appropriate backend models (Claude, Codex, OpenCode)
• Resolving inter-lane conflicts and blocking conditions
• Providing a real-time chat interface for human-in-the-loop oversight

Sources: README.md

Architecture

The orchestration system is composed of multiple layers:

graph TD
    subgraph "Frontend (Dashboard)"
        CP[ConductorPage]
        CH[ConductorChat]
        LP[Lanes Panel]
        TCP[ToolCallsPanel]
    end
    
    subgraph "Backend (Rust/Tauri)"
        MS[Main State]
        CS[ConductorState]
    end
    
    subgraph "MCP Server (Python)"
        ROS[RuntimeOrchestrationService]
        RCDS[RuntimeConductorDispatchService]
        PC[PlanConductor]
        CC[CoConductor]
        AC[AgentOrchestrator]
        CCM[ConductorComms]
    end
    
    CP -->|Tauri Commands| MS
    CH -->|conductor_start/send| CS
    CS -->|MCP Tools| ROS
    ROS --> RCDS
    RCDS --> PC
    RCDS --> CC
    PC --> AC
    CC --> AC
    AC --> CCM

Core Components

PlanConductor

The PlanConductor is responsible for high-level task planning. It receives goals and breaks them into discrete execution lanes, establishing dependencies and ordering constraints.

Key Responsibilities:

• Parse incoming task descriptions
• Generate execution plans with lane definitions
• Set lane blocking conditions
• Track plan progress through completion

Sources: mcp/server/aidocs_mcp/plan_conductor.py

CoConductor

The CoConductor operates as a parallel supervisory agent that assists the primary conductor. It handles secondary routing decisions and provides fallback reasoning when the main conductor encounters ambiguous situations.

Key Responsibilities:

• Parallel task assessment
• Fallback routing decisions
• Conflict resolution between lanes
• Escalation handling

Sources: mcp/server/aidocs_mcp/co_conductor.py

RuntimeOrchestrationService

The RuntimeOrchestrationService serves as the central service entry point for all orchestration operations. It manages session state and dispatches requests to appropriate conductor components.

Key Responsibilities:

• Session lifecycle management
• Service initialization and teardown
• Request routing to PlanConductor/CoConductor
• State synchronization with dashboard

Sources: mcp/server/aidocs_mcp/runtime_orchestration_service.py

RuntimeConductorDispatchService

The RuntimeConductorDispatchService handles the low-level dispatch of tasks to specific backends. It manages connection pooling, request queuing, and response aggregation.

Key Responsibilities:

• Backend selection (claude/codex/opencode)
• Request dispatch and retry logic
• Response aggregation
• Connection state management

Sources: mcp/server/aidocs_mcp/runtime_conductor_dispatch_service.py

AgentOrchestrator

The AgentOrchestrator coordinates the actual execution of tasks within each lane. It manages tool calls, maintains execution context, and handles error recovery.

Key Responsibilities:

• Lane-level task execution
• Tool call management and policy enforcement
• Execution state persistence
• Error recovery and retry

Sources: mcp/server/aidocs_mcp/agent_orchestrator.py

ConductorComms

The ConductorComms module handles inter-process and inter-service communication. It provides the messaging substrate for conductor components and the dashboard.

Key Responsibilities:

• Message formatting and serialization
• Transport abstraction
• Session message routing
• Event broadcasting

Sources: mcp/server/aidocs_mcp/conductor_comms.py

State Management (Rust Backend)

The Tauri backend maintains conductor state across sessions using a global state map.

graph TD
    subgraph "ConductorState"
        PID[process: Option Child]
        OUT[output: Vec f64, String, String]
        BE[backend: Option String]
        MD[model: Option String]
        PORT[opencode_port: Option u16]
        CSID[claude_session_id: Option String]
        COXSID[codex_session_id: Option String]
        SIF[codex_send_in_flight: bool]
    end
    
    subgraph "Global State"
        CONDUCTORS[HashMap ConductorKey ConductorState]
    end
    
    CONDUCTORS -->|key: (root, session_id)| PID
    CONDUCTORS -->|key: (root, session_id)| BE

ConductorKey Structure

ConductorState Fields

Sources: apps/aidocs-dashboard/src-tauri/src/main.rs:1-50

Lanes System

Lanes are the fundamental execution unit in the orchestration system. Each lane represents an isolated task pipeline that can run independently or with dependencies on other lanes.

Lane States

Blocking Reasons

Lanes can be blocked by:

• Unmet dependency lanes
• Resource constraints
• Security policy gates
• External input waiting

Sources: apps/aidocs-dashboard/src/ConductorPage.tsx

Dashboard Integration

ConductorPage

The ConductorPage component provides the main dashboard interface for conductor operations.

interface ConductorPageProps {
  progressPercent: number;
  conductorLanes: Lane[];
  runnableLaneIds: string[];
  blockedReasons: Record<string, string[]>;
  recentExecution: ExecutionEvent[];
  configEntries: ConfigEntry[];
  selectedSessionId: string;
  projectRoot: string;
  sessionId: string;
}

Components:

ConductorChat

The chat interface supports multiple message recipients:

Message roles displayed:

Sources: apps/aidocs-dashboard/src/ConductorPage.tsx

Multi-Backend Routing

The orchestration system supports routing to different AI backends:

Supported Backends

Routing Configuration

interface RouteConfig {
  backend: "claude" | "codex" | "opencode";
  models: {
    claude: string;
    codex: string;
    opencode: string;
  };
}

Backend Selection Logic

1. Check conductor.backend config for default
2. Evaluate task requirements
3. Consider model capabilities
4. Apply routing policies

Execution Events

Execution events track all conductor activity:

Event Structure

interface ExecutionEvent {
  event_id: string;
  event_kind: string;
  capability_name?: string;
  action_kind?: string;
  session_id: string;
  observed_at: string;
  lane?: string;
  audit?: {
    logicalMode?: string;
    nativeMode?: string;
    fallbackUsed?: boolean;
  };
  payload?: {
    args_preview?: string;
    result_preview?: string;
    result_summary?: string;
  };
}

Audit Trail

Sources: apps/aidocs-dashboard/src/ExecutionPage.tsx

Workflow

sequenceDiagram
    participant User
    participant Dashboard
    participant Conductor
    participant PlanConductor
    participant CoConductor
    participant AgentOrchestrator
    participant Backend

    User->>Dashboard: Send message/goal
    Dashboard->>Conductor: route_prompt(goal)
    Conductor->>PlanConductor: create_plan(goal)
    PlanConductor-->>Conductor: lanes[], dependencies[]
    Conductor->>CoConductor: validate_plan(lanes)
    CoConductor-->>Conductor: validation_result
    
    loop For each runnable lane
        Conductor->>AgentOrchestrator: execute_lane(lane)
        AgentOrchestrator->>Backend: dispatch(task)
        Backend-->>AgentOrchestrator: result
        AgentOrchestrator-->>Conductor: lane_status
    end
    
    Conductor-->>Dashboard: progress_update
    Dashboard->>User: Display results

Message Flow

Messages flow through the system with role-based routing:

graph LR
    subgraph "Dashboard"
        CH[ConductorChat]
    end
    
    subgraph "Backend"
        CCM[ConductorComms]
        PC[PlanConductor]
        CC[CoConductor]
    end
    
    CH-->|Message| CCM
    CCM-->|Route| PC
    CCM-->|Route| CC
    
    PC-->|Plan| CCM
    CC-->|Response| CCM
    CCM-->|Aggregated| CH

Configuration

Conductor Settings

Lane Configuration

Lanes are configured via the plan conductor with:

• Dependencies: Ordered constraint list
• Blocking conditions: Runtime predicates
• Resource requirements: CPU, memory, tool access
• Timeout settings: Per-lane execution limits

Best Practices

Session Management

1. Use persistent sessions - Resume work instead of restarting
2. Monitor lane states - Watch for blocking conditions
3. Review execution events - Track capability usage

Error Handling

1. Check blocked reasons - First step in debugging stuck lanes
2. Review fallback usage - Indicates routing issues
3. Examine audit trails - Understand routing decisions

Security

• Security gates apply to all conductor operations
• Lane isolation prevents cross-task contamination
• RBAC controls conductor access

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

Related Pages

Related topics: MCP Server Architecture, Conductor & Orchestration, Configuration Management

Security & Access Control

AIDOCS implements a layered security architecture designed to govern AI agent behavior within development environments. The system provides fine-grained control over tool usage, bash command execution, prompt integrity, and permission escalation through multiple enforcement mechanisms working in concert.

Overview

The Security & Access Control subsystem in AIDOCS operates as a multi-stage guard system that intercepts and evaluates agent requests before they reach system resources. It combines heuristic analysis, role-based access control (RBAC), tool policy enforcement, and output sanitization to create a defense-in-depth approach for AI-assisted development.

Core Security Components

Architecture

graph TD
    A[Agent Request] --> B[Access Gate]
    B --> C{Security Enabled?}
    C -->|No| Z[Allow]
    C -->|Yes| D[Heuristic Judge]
    D --> E{Risk Score}
    E -->|Low| F[RBAC Check]
    E -->|Medium| G[Gate Permission Required]
    E -->|High| H[Block]
    F --> I{Has Permission?}
    I -->|Yes| J[Tool Policy Check]
    I -->|No| H
    J --> K{Command Allowed?}
    K -->|Yes| L[Execute]
    K -->|No| H
    G --> M[Request Approval]
    M -->|Approved| L
    M -->|Denied| H
    L --> N[Output Guard]
    N --> O[Filtered Response]

Access Gate

The Access Gate serves as the central authorization checkpoint for all agent requests. It evaluates incoming requests against the current security posture and determines whether additional verification is needed.

Configuration Paths

The system exposes security settings through configurable paths that control different aspects of enforcement:

Sources: apps/aidocs-dashboard/src/dashboardModals.tsx

Security Toggle Behavior

When security.enforce is disabled, the following protections are removed:

• Bash allowlist enforcement
• Raw tool blocking
• Destructive command protection

Agents gain the ability to use any tool freely when enforcement is disabled. This setting should only be modified with explicit user confirmation through the security change confirmation modal.

Sources: apps/aidocs-dashboard/src/dashboardModals.tsx

Heuristic Judge

The Heuristic Judge performs real-time risk assessment on agent requests by analyzing patterns and content characteristics. It assigns risk scores that determine the level of scrutiny a request receives.

Risk Categories

The system categorizes risks into several domains:

Sources: mcp/server/aidocs_mcp/skill_scanner.py

Risk Severity Levels

Output Guard

The Output Guard monitors and sanitizes content flowing from agent responses. It detects potential security issues including prompt injection attempts and sensitive data leakage.

Prompt Injection Detection

The system recognizes multiple categories of prompt injection patterns:

_PROMPT_INJECTION_PATTERNS = [
    ("system_override", "ignore/forget previous instructions"),
    ("role_hijack", "you are now a different AI"),
    ("instruction_inject", "XML tag instruction injection"),
    ("delimiter_escape", "code block instruction injection"),
    ("hidden_instruction", "URGENT: ignore/override"),
]

Sources: mcp/server/aidocs_mcp/output_guard.py

Sensitive Content Detection

The Output Guard applies redaction markers in the format [REDACTED:{category}] when sensitive content is detected and redaction is enabled.

Sources: mcp/server/aidocs_mcp/output_guard.py

Role-Based Access Control (RBAC)

The RBAC system provides granular permission management for agent capabilities. It defines roles, permissions, and escalation paths that govern what actions agents can perform.

Permission States

Permissions can exist in three states:

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

RBAC Table Structure

The RBAC page displays permissions in a structured table format:

Sources: apps/aidocs-dashboard/src/RBACPage.tsx

Escalation Management

The RBAC system supports permission escalation with the following attributes:

Tool Policy

Tool Policy manages bash command execution through an allowlist/denylist mechanism. It provides fine-grained control over shell commands that agents can execute.

Policy Structure

graph LR
    A[Command] --> B{Policy Check}
    B -->|allow| C[Execute]
    B -->|deny| D[Block]
    B -->|bubble| E[Request Approval]
    B -->|modified| F[Execute with Modification]

Bash Policy Panel

The Dashboard provides a visual interface for managing shell policies:

Sources: apps/aidocs-dashboard/src/BashPolicyPanel.tsx

Policy Layer System

Bash policies support layered configuration with the following characteristics:

• Policies can be defined at different layers
• Active layer determines which policy configuration is currently in effect
• Changes made at the active layer are tracked separately
• Fallback default behavior is configurable

Enforcement Controller

The Enforcement Controller orchestrates all security mechanisms and ensures consistent policy application across the system.

Enforcement Actions

Live Monitoring

The Live Page in the Dashboard provides real-time visibility into enforcement events:

graph TD
    A[Agent Request] --> B[Gate Permission Check]
    B --> C{Permission Status}
    C -->|Required| D[Display in UI]
    C -->|Approved| E[Continue Execution]
    C -->|Rejected| F[Block and Log]
    D --> G{User Action}
    G -->|Approve| E
    G -->|Reject| F

The gate permission requests appear in the Live Page with:

• Permission name being requested
• Requester label
• Approve/Reject buttons for user response

Sources: apps/aidocs-dashboard/src/LivePage.tsx

Quick Actions

The Dashboard provides administrative quick actions for security management:

Sources: apps/aidocs-dashboard/src/LivePage.tsx

Statistics Dashboard

The Live Page includes a stat tile strip showing real-time security metrics:

Blocked and Failed counts display with danger tone styling when greater than zero, providing immediate visual feedback for security administrators.

Configuration Management

Setting Origin Tracking

Individual settings can be traced to their origin layer through the Setting Detail Panel:

graph TD
    A[Setting Path] --> B{Origin Count}
    B -->|Single| C[Display Source Layer]
    B -->|Multiple| D[Per-Leaf Origin Table]
    D --> E[List of Leaf Paths]
    D --> F[Layer per Leaf]

Settings with multiple origins display a collapsible table showing which layer each configuration leaf originated from.

Sources: apps/aidocs-dashboard/src/SettingDetailPanel.tsx

Layer Tone Indicators

Connection Status

The Castle Shell status bar displays MCP connection state:

Sources: apps/aidocs-dashboard/src/CastleShell.tsx

Security Workflow Summary

graph LR
    A[Request] --> B{Dev Mode?}
    B -->|Yes| C[Additional Access]
    B -->|No| D{Normal Checks}
    D --> E{Security Enforce?}
    E -->|No| F[Minimal Security]
    E -->|Yes| G[Full Enforcement]
    G --> H[Heuristic Analysis]
    H --> I{Risk Level}
    I -->|Low| J[RBAC]
    I -->|Medium| K[Gate Permission]
    I -->|High| L[Block]
    J --> M{Has Permission?}
    M -->|Yes| N[Tool Policy]
    M -->|No| L
    N --> O{Allowed?}
    O -->|Yes| P[Execute + Output Guard]
    O -->|No| L
    K --> Q{Approved?}
    Q -->|Yes| P
    Q -->|No| L

Summary

AIDOCS Security & Access Control provides comprehensive protection for AI-assisted development through:

1. Centralized Access Gate - Single entry point for all authorization decisions
2. Heuristic Analysis - Automated risk scoring based on request patterns
3. RBAC Engine - Fine-grained permission management with escalation support
4. Tool Policy - Command allowlisting with layered configuration
5. Output Guard - Prompt injection detection and sensitive data redaction
6. Real-time Monitoring - Dashboard visibility into security events and statistics

The system is designed with defense-in-depth principles, ensuring that multiple independent checks must pass before potentially risky operations are executed.

Related Pages

Related topics: Memory System

Indexing & Retrieval System

Overview

The Indexing & Retrieval System is the core backbone of AIDOCS, enabling AI coding agents to efficiently locate, analyze, and retrieve code symbols, semantic concepts, and structural information across a codebase. It transforms a raw repository into a queryable, memory-augmented context that allows agents to resume work without re-discovering the codebase on every session.

The system operates as a layered pipeline that:

1. Discovers code files based on language descriptors
2. Parses files to extract symbols, outlines, and semantic metadata
3. Indexes extracted data into structured storage
4. Serves retrieval queries through MCP tools (ai_find, ai_bundle, ai_investigate, ai_trace)

This architecture is designed for persistent memory across sessions, fast targeted lookups, and multi-language support with configurable heuristics.

Sources: mcp/server/README.md

Architecture Overview

graph TD
    A[Codebase Files] --> B[Language Descriptors]
    B --> C[File Discovery]
    C --> D[Outline Extractors]
    D --> E[Symbol Parsers]
    E --> F[Index Storage Layer]
    F --> G[index_store.py]
    F --> H[code_index_store.py]
    G --> I[Retrieval Query Pipeline]
    H --> I
    I --> J[semantic_search.py]
    J --> K[code_index_symbol_search_service.py]
    K --> L[MCP Tools: ai_find, ai_bundle, ai_investigate]

Language Descriptor System

Purpose

Language descriptors inform the indexer which files belong to a project, what support tier applies, and what heuristic semantics influence indexing behavior. They act as the discovery and classification layer for the entire indexing pipeline.

Sources: mcp/INDEX_LANGUAGE_DESCRIPTORS.md

Descriptor Locations

Project-local descriptors can extend or override built-in behavior, allowing teams to define custom language support or refine heuristics for their specific codebase.

Sources: mcp/INDEX_LANGUAGE_DESCRIPTORS.md

Supported Keys

Discovery Keys (at least one required):

• extensions — file extensions (e.g., .py, .ts)
• suffixes — alternative naming patterns
• include_globs — glob patterns for discovery

Core Keys:

Semantics Keys (influence indexing behavior):

Sources: mcp/INDEX_LANGUAGE_DESCRIPTORS.md Sources: mcp/server/aidocs_mcp/language_descriptors.py

Loading Descriptors

Descriptors are loaded through load_language_descriptors() which implements a caching strategy:

graph TD
    A[load_language_descriptors] --> B{Cache Hit?}
    B -->|Yes, schema version match| C[Return cached]
    B -->|No| D[Compute fingerprint]
    D --> E{Fingerprint match?}
    E -->|Yes| F[Return cached]
    E -->|No| G[Scan descriptor directories]
    G --> H[Load TOML files]
    H --> I[Filter by enabled languages]
    I --> J[Return descriptors]

The function checks the schema version first, then compares file fingerprints to avoid unnecessary I/O. Only descriptors matching the enabled language set are loaded.

Sources: mcp/server/aidocs_mcp/language_descriptors.py

Outline Extraction

Role of Outline Extractors

Outline extractors parse source files to identify structural elements—classes, functions, methods, interfaces, and other symbols—and produce a lightweight outline representation. This is the primary mechanism for symbol discovery during indexing.

Sources: mcp/server/aidocs_mcp/outline_extractors/__init__.py

Architecture

The outline extractor system uses a modular design with language-specific implementations. Each extractor conforms to a common interface that:

1. Accepts a file path and content
2. Returns structured symbol data with line numbers, kinds, and containers
3. Handles language-specific parsing nuances

The __init__.py module exports the extractor registry and common data structures used across all language extractors.

Sources: mcp/server/aidocs_mcp/outline_extractors/__init__.py

Index Storage Layer

Two-Store Architecture

The indexing system maintains two complementary storage mechanisms:

graph LR
    A[index_store.py] --> B[General Index]
    A --> C[File-level metadata]
    A --> D[Language classification]
    E[code_index_store.py] --> F[Symbol Index]
    E --> G[Symbol definitions]
    E --> H[Reference mappings]
    E --> I[Container relationships]

index_store.py handles:

• File-level metadata and indexing state
• Language classification per file
• Index-wide configuration and statistics

code_index_store.py handles:

• Symbol definitions extracted from source
• Reference relationships between symbols
• Container hierarchies (e.g., class → method relationships)

Sources: mcp/server/aidocs_mcp/index_store.py Sources: mcp/server/aidocs_mcp/code_index_store.py

Symbol Index Structure

The symbol index maintains structured records for each extracted symbol:

This structure enables efficient filtering by kind, container, and location during retrieval queries.

Sources: mcp/server/METHODS.md

Retrieval Services

Semantic Search

semantic_search.py implements concept-level search capabilities that go beyond exact symbol matching. It enables:

• Concept queries — searching by semantic meaning rather than exact names
• Fuzzy matching — handling typos and partial matches
• Ranking — scoring results by relevance

The semantic search layer bridges the gap between natural language queries and structured symbol data, enabling agents to find code using descriptive terms.

Sources: mcp/server/aidocs_mcp/semantic_search.py

Symbol Search Service

code_index_symbol_search_service.py provides the core symbol-level search functionality:

• Symbol lookup — find symbols by exact or partial name match
• Reference tracing — locate all usages of a symbol
• Kind filtering — search within specific symbol types
• Scope resolution — navigate symbol containers

This service is the primary engine behind the ai_find MCP tool, which supports multiple search modes:

Sources: mcp/server/aidocs_mcp/code_index_symbol_search_service.py Sources: mcp/server/aidocs_mcp/claude_hook.py

MCP Tool Interface

Core Retrieval Tools

The indexing system exposes retrieval capabilities through these MCP tools:

ai_find — Unified symbol and reference search across indexed code.

ai_investigate — Broad concept investigation with ranked results across layers.

ai_bundle — Retrieve comprehensive context for a file, path, or concept.

ai_trace — Cross-layer relationship tracing for fields, settings, or services.

ai_get_symbol_snippet — Retrieve exact symbol body with container context.

ai_get_symbol_info — Retrieve symbol metadata (signature, constructor, enum, API).

Sources: mcp/README.md

Read Pipeline

Line-based reading flows through a shared read pipeline with strict mode enforcement:

graph TD
    A[ai_get_lines] --> B[gate: strict mode]
    B --> C{Path valid?}
    C -->|No| D[Refusal]
    C -->|Yes| E[Check managed mode]
    E --> F[indexed_read_block]
    F --> G[Return lines]

Strict mode enforces:

• No absolute path inputs
• No .. traversal
• Zone restrictions (PROJECT_INTERNAL, MEMORY_INTERNAL only)

Sources: mcp/server/aidocs_mcp/server_code_edit_tools.py

Configuration Options

Index Settings

Configuration options in config_schema.py control indexing behavior:

Sources: mcp/server/aidocs_mcp/config_schema.py

Layer Inference

The retrieval system infers architectural layers for search results, enabling context-aware queries:

Layer inference helps agents understand where discovered code fits in the system architecture and find code at appropriate abstraction levels.

Sources: mcp/server/METHODS.md

Session Persistence

The indexing system supports persistent sessions that maintain index state across agent invocations:

• Session-based indexing — indexes can be tied to session IDs
• Project sync — project_sync_indexes keeps indexes current with codebase
• Managed mode — enforces controlled editing with session tracking

This persistence enables the "resume work instead of rediscovering" core value proposition of AIDOCS.

Sources: mcp/README.md Sources: mcp/server/aidocs_mcp/claude_hook.py

Workflow Summary

graph LR
    A[Initialize Project] --> B[Load Language Descriptors]
    B --> C[Discover Files]
    C --> D[Extract Outlines]
    D --> E[Parse Symbols]
    E --> F[Store in Index]
    F --> G[Ready for Retrieval]
    G --> H[ai_find / ai_investigate]
    G --> I[ai_bundle / ai_trace]
    H --> J[Symbol Search Service]
    I --> K[Semantic Search]
    J --> L[Agent Context]
    K --> L

Related Documentation

• METHODS.md — Complete MCP tool reference
• INDEX_LANGUAGE_DESCRIPTORS.md — Language descriptor specification
• config_schema.py — Configuration reference

Related Pages

Related topics: System Architecture Overview, Security & Access Control

Configuration Management

Overview

AIDOCS provides a layered, hierarchical configuration system that enables persistent memory, indexed retrieval, and orchestration for AI coding agents. The configuration architecture supports multiple levels of override, from system defaults down to per-project and per-session settings.

Sources: README.md

Configuration Architecture

AIDOCS uses a layered configuration model where settings cascade from base defaults through environment-specific overrides to project-specific customizations.

graph TD
    A[System Defaults] --> B[Environment Variables]
    B --> C[aidocs.toml Base]
    C --> D[Project .aidocs/]
    D --> E[Session Overrides]
    E --> F[Runtime Resolution]
    
    A -->|Low Priority| F
    E -->|High Priority| F

Configuration Files

Sources: README.md

Core Configuration: aidocs.toml

The primary runtime configuration file defines system-wide and per-project settings.

Configuration Sections

# aidocs.toml structure (conceptual)
[dev]
dev_mode = false  # Enable editing MCP server source files

[security]
allow_config_edit = false  # Allow agents to modify config via tool calls
enforce = true  # Enable tool gates and bash allowlist

[memory]
# Memory and indexing settings
retention_days = 30
index_on_startup = true

[mcp]
# MCP server connection settings
transport = "stdio"
command = "aidocs-mcp"

Security Configuration

The security section controls agent capabilities and tool access:

Sources: apps/aidocs-dashboard/src/dashboardModals.tsx, apps/aidocs-dashboard/src/TomlConfigsPage.tsx

Warning Messages for Security Changes:

// From dashboardModals.tsx
{settingPath === "dev.dev_mode" && "Enables editing AIDOCS MCP server source files. Only use when actively developing AIDOCS."}
{settingPath === "security.allow_config_edit" && "Allows agents to modify AIDOCS config via tool calls. The agent can change gate settings, conductor config, and other project settings."}
{settingPath === "security.enforce" && "Disabling tool gates removes bash allowlist, raw tool blocking, and destructive command protection. Agents can use any tool freely."}

Shell Policy Configuration

The bash policy system provides fine-grained control over shell command execution with a three-tier decision model.

Policy Actions

Policy Display

The dashboard visualizes policy counts per layer:

<span className="bash-policy-count bash-policy-count-allow">{counts.allowEff} allow</span>
<span className="bash-policy-count bash-policy-count-deny">{counts.denyEff} deny</span>
<span className="bash-policy-count bash-policy-count-bubble">{counts.bubbleEff} bubble</span>
<span className="bash-policy-count bash-policy-count-mod">{counts.modifiedAtActive} set at {activeLayer}</span>

Sources: apps/aidocs-dashboard/src/BashPolicyPanel.tsx

Filter Controls

Policy entries can be filtered using the search and category chips:

const filters = ["all", "allow", "deny", "bubble", "modified"] as const;

Action Tokens (Prompt Classification)

Action Tokens are YAML-based language files that define how user prompts are classified and routed.

Structure

# action_tokens/en.yaml (conceptual structure)
intent_tokens:
  - name: "implement"
    pattern: "implement|create|build|add"
    action: "code_generation"
    
  - name: "investigate"
    pattern: "investigate|analyze|trace"
    action: "code_analysis"

Configuration Categories

The TOML configuration page in the dashboard provides tabs for different configuration domains:

Sources: apps/aidocs-dashboard/src/TomlConfigsPage.tsx, mcp/README.md

Setup Wizard Configuration Flow

The setup wizard guides users through initial project configuration:

graph TD
    A[Welcome] --> B[Project Selection]
    B --> C[Environment Detection]
    C --> D[Configuration]
    D --> E[Done]
    
    B -->|Select folder| B
    C -->|Missing deps| F[Install Dependencies]
    F --> C

Setup Steps

Configuration Results

After setup, the wizard displays:

<div className="setup-checklist">
  <div className="setup-check pass">
    <span>MCP configured</span>
    <span>{configResult.mcp_path}</span>
  </div>
  <div className="setup-check pass">
    <span>Hooks registered</span>
    <span>{configResult.hooks_path}</span>
  </div>
  <div className="setup-check pass">
    <span>Project initialized</span>
  </div>
</div>

Sources: apps/aidocs-dashboard/src/SetupWizardPage.tsx

Environment Detection

The wizard detects installed tools and authentication status:

{/* Sign-in button for detected but unauthenticated hosts */}
{h.authenticated === false && (
  <button onClick={() => {
    const url = h.name.includes("Claude") ? "https://claude.ai" : "https://platform.openai.com/api-keys";
    invoke("open_url", { url });
  }}>Sign in</button>
)}

Configuration Resolution

Settings follow a precedence hierarchy where higher layers override lower ones:

graph LR
    A[Base Defaults] --> B[Project Config]
    B --> C[Session State]
    C --> D[Runtime Values]
    
    style A fill:#e1e1e1
    style D fill:#90EE90

Layer Model

TOML Document Management

The dashboard provides a unified interface for managing TOML configuration documents:

// Document filtering by category
const categoryPrefix = "mcp/server/aidocs_mcp/index_languages/";
const filteredDocuments = tomlDocuments.filter((d) => d.path.startsWith(categoryPrefix));

Document Table Columns

Command-Line Configuration

AIDOCS provides CLI commands for configuration management:

aidocs setup                  # Configures MCP, hooks, and project init
aidocs doctor                 # Verifies installation and configuration

Sources: README.md

Summary

The AIDOCS configuration management system provides:

1. Hierarchical Override: Settings cascade from system defaults through project-specific configurations
2. Security Controls: Fine-grained control over agent capabilities and tool access
3. Shell Policy: Three-tier command execution model (allow/deny/bubble)
4. Language Support: Extensible action token system for prompt classification
5. Dashboard Integration: Visual configuration management through the Tauri-based dashboard
6. CLI Tools: Command-line utilities for setup and validation

All configuration is designed to support the core goal of giving AI coding agents persistent memory, indexed retrieval, and orchestration while maintaining security and operational safety.

Doramagic Pitfall Log

Doramagic extracted 9 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | host_targets=mcp_host, claude, claude_code, cursor

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | no_demo; severity=medium

6. Security or permission risk: v2.0.0 — Unified AccessGate & Agent Enforcement

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v2.0.0 — Unified AccessGate & Agent Enforcement. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.0

7. Security or permission risk: v2.0.3 — Token Tracking & Dashboard Fixes

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v2.0.3 — Token Tracking & Dashboard Fixes. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/cristian1991/AIDOCS/releases/tag/v2.0.3

8. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | issue_or_pr_quality=unknown

9. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1153124183 | https://github.com/cristian1991/AIDOCS | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using AIDOCS with real data or production workflows.

• v2.0.3 — Token Tracking & Dashboard Fixes - github / github_release
• v2.0.0 — Unified AccessGate & Agent Enforcement - github / github_release
• Configuration risk needs validation - GitHub / issue