# ambalavanan-m/ai-shell architecture

> Architecture diagram of the GitHub repository ambalavanan-m/ai-shell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ambalavanan-m/ai-shell
- Repository: https://github.com/ambalavanan-m/ai-shell

## Overview

AI-Shell is a Linux command interpreter with a natural-language assistant, a human-reviewed safety pipeline, and system-programming analysis commands. Its principal workflow is user input → parsing and command generation → risk analysis and approval where AI is involved → execution. The README also documents built-ins, job control, macros, system information, compiler and ELF analysis, debugging, and error assistance. Only README.md is present, so implementation paths and undocumented call relationships cannot be established; edges below reflect documented behavior only.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell Runtime"]
  node_shell["Shell Loop"]
  node_parser["Command Parser"]
  node_builtins["Built-in Commands"]
  node_macros["Macro Processor"]
  node_history["History"]
end

subgraph group_safety["AI And Safety"]
  node_ai["AI Assistant"]
  node_service["AI Service"]
  node_risk["Risk Analyzer"]
  node_approval["Human Approval"]
  node_errorhelp["Error Assistant"]
end

subgraph group_analysis["System Analysis"]
  node_sysinfo["System Information"]
  node_compiler["Compiler Pipeline"]
  node_assembler["Assembly Analysis"]
  node_elf["ELF Analyzer"]
  node_debugger["GDB Interface"]
end

subgraph group_execution["Process Execution"]
  node_executor["Command Executor"]
  node_jobs["Job Control"]
  node_signals["Signal Handling"]
end

node_user(("User"))
node_tools["Linux Programs"]

node_user -->|"enters commands"| node_shell
node_shell -->|"parses input"| node_parser
node_shell -->|"handles built-ins"| node_builtins
node_shell -->|"expands macros"| node_macros
node_shell -->|"records history"| node_history
node_parser -->|"dispatches commands"| node_executor
node_executor -->|"executes programs"| node_tools
node_executor -->|"manages jobs"| node_jobs
node_jobs -->|"handles signals"| node_signals
node_user -->|"requests command"| node_ai
node_ai -->|"requests generation"| node_service
node_service -->|"returns candidate"| node_ai
node_ai -->|"validates candidate"| node_parser
node_ai -->|"assesses command"| node_risk
node_risk -->|"requests review"| node_approval
node_approval -->|"approves execution"| node_executor
node_user -->|"requests system data"| node_sysinfo
node_user -->|"requests compilation analysis"| node_compiler
node_compiler -->|"exposes assembly stage"| node_assembler
node_user -->|"requests ELF analysis"| node_elf
node_user -->|"requests debugging"| node_debugger
node_user -->|"requests error help"| node_errorhelp

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_parser,node_builtins,node_macros,node_history,node_user toneBlue
class node_ai,node_service,node_risk,node_approval,node_errorhelp toneAmber
class node_sysinfo,node_compiler,node_assembler,node_elf,node_debugger toneMint
class node_executor,node_jobs,node_signals toneRose
class node_tools toneIndigo
```

## Components

### Shell Runtime

- **Shell Loop**
- **Command Parser**
- **Built-in Commands**
- **Macro Processor**
- **History**

### AI And Safety

- **AI Assistant**
- **AI Service**
- **Risk Analyzer**
- **Human Approval**
- **Error Assistant**

### System Analysis

- **System Information**
- **Compiler Pipeline**
- **Assembly Analysis**
- **ELF Analyzer**
- **GDB Interface**

### Process Execution

- **Command Executor**
- **Job Control**
- **Signal Handling**

### Other components

- **User**
- **Linux Programs**

## Connections

- User → Shell Loop: enters commands (evidence: `README.md`)
- Shell Loop → Command Parser: parses input (evidence: `README.md`)
- Shell Loop → Built-in Commands: handles built-ins (evidence: `README.md`)
- Shell Loop → Macro Processor: expands macros (evidence: `README.md`)
- Shell Loop → History: records history (evidence: `README.md`)
- Command Parser → Command Executor: dispatches commands (evidence: `README.md`)
- Command Executor → Linux Programs: executes programs (evidence: `README.md`)
- Command Executor → Job Control: manages jobs (evidence: `README.md`)
- Job Control → Signal Handling: handles signals (evidence: `README.md`)
- User → AI Assistant: requests command (evidence: `README.md`)
- AI Assistant → AI Service: requests generation (evidence: `README.md`)
- AI Service → AI Assistant: returns candidate (evidence: `README.md`)
- AI Assistant → Command Parser: validates candidate (evidence: `README.md`)
- AI Assistant → Risk Analyzer: assesses command (evidence: `README.md`)
- Risk Analyzer → Human Approval: requests review (evidence: `README.md`)
- Human Approval → Command Executor: approves execution (evidence: `README.md`)
- User → System Information: requests system data (evidence: `README.md`)
- User → Compiler Pipeline: requests compilation analysis (evidence: `README.md`)
- Compiler Pipeline → Assembly Analysis: exposes assembly stage (evidence: `README.md`)
- User → ELF Analyzer: requests ELF analysis (evidence: `README.md`)
- User → GDB Interface: requests debugging (evidence: `README.md`)
- User → Error Assistant: requests error help (evidence: `README.md`)
