🧠 What Is This?

LaptopAI-Agent is a fully local, privacy-first autonomous AI agent that manages and reasons about your laptop. It combines:

• A LangGraph reasoning loop — multi-step planning with tool use, up to 10 agentic iterations per query
• A local LLM via Ollama — default qwen2.5-coder:7b for high tool-calling accuracy, no internet required
• A ChromaDB RAG layer — ingest your git repos, configs, logs, and docs; retrieve relevant context at inference time
• An MCP server — expose all tools to Claude Desktop / Claude Code over stdio
• A SHA-256 chained audit log — append-only, tamper-evident JSONL record of every agent action

Ask it: "Which of my repos have uncommitted changes?" or "My disk is 87% full — what's taking space in C:\Gitrepos?" and it will reason, call tools, and respond — entirely on your machine.

⚡ Quick Start

# 1. Pull the recommended local model
ollama pull qwen2.5-coder:7b

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start chatting
python main.py chat

# 4. Check system health dashboard
python main.py status

# 5. List all git repos + remote URLs + branch
python main.py repos

# 6. Ingest documents into local RAG
python main.py ingest C:\Gitrepos\LaptopAI-Agent\docs

# 7. Start MCP server (for Claude Desktop / Claude Code)
python main.py mcp

# 8. Verify audit log chain integrity
python main.py verify-audit

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        User / MCP Client                            │
│                    (CLI chat or Claude Desktop)                     │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ query
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    LangGraph Agent Loop                             │
│                                                                     │
│   ┌──────────┐   tool_calls?   ┌──────────────┐                    │
│   │  agent   │ ──────────────► │  ToolNode    │                    │
│   │  (LLM)   │ ◄────────────── │ (LangChain)  │                    │
│   └──────────┘   tool results  └──────────────┘                    │
│        │                              │                             │
│   max 10 iterations            Permission Guard                     │
│        │                       + Audit Log                          │
│        ▼                                                            │
│   Final response                                                    │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
          ┌─────────────────────┼────────────────────────┐
          ▼                     ▼                        ▼
┌──────────────────┐  ┌─────────────────────┐  ┌────────────────────┐
│   Ollama (LLM)   │  │  ChromaDB (RAG)     │  │  System Tools      │
│                  │  │                     │  │                    │
│ qwen2.5-coder:7b │  │ all-MiniLM-L6-v2   │  │ psutil, git,       │
│ localhost:11434  │  │ cosine similarity   │  │ pathlib, subprocess│
│ temperature=0.1  │  │ 512-token chunks    │  │                    │
│ NO API KEY       │  │ 64-token overlap    │  │ Permission Guard   │
└──────────────────┘  └─────────────────────┘  └────────────────────┘

🛠️ Available Tools

Every tool call is intercepted by the Permission Guard and written to the chained audit log.

MCP Tools (exposed to Claude Desktop / Claude Code)

🔐 Security Model

LaptopAI-Agent is built on the assumption that a local agent with file-write access is a high-privilege process. Three controls enforce safe operation:

1. 🛡️ Permission Guard

Every tool call passes through PermissionGuard before execution:

Allowed write paths:   C:\Gitrepos, C:\Users\Sunil\Documents, C:\Users\Sunil\Desktop
Blocked paths:         C:\Windows\System32, C:\Program Files
Allowed commands:      git, python, pip, npm, node, powershell, Get-ChildItem, ...
Manual approval for:   rm, Remove-Item, Format-*, reg delete
Max file write:        100 MB
Max execution time:    30 seconds

Any violation raises PermissionError and the tool call is blocked — the LLM never sees the result.

2. 🔗 SHA-256 Chained Audit Log

Every agent action writes to logs/audit.jsonl as a hash chain — each entry commits the hash of the previous entry, making any historical modification detectable:

{
  "timestamp": "2026-06-05T00:00:00+00:00",
  "event_type": "TOOL_CALL",
  "actor": "LaptopAI-Agent",
  "action": "read_file",
  "target": "C:\\Gitrepos\\ZKP-RA\\paper.tex",
  "result": "32650 chars",
  "prev_hash": "a3f1cc...",
  "hash": "9d2c44..."   // SHA-256(this entry + prev_hash)
}

Verify the full chain integrity at any time:

python main.py verify-audit
# Chain valid (847 entries)

3. 🔒 Zero External Calls

No tokens, queries, files, or embeddings ever leave your machine.

🧩 Claude Desktop / Claude Code Integration

Add to claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "laptop-ai": {
      "command": "python",
      "args": ["C:\\Gitrepos\\LaptopAI-Agent\\main.py", "mcp"],
      "cwd": "C:\\Gitrepos\\LaptopAI-Agent"
    }
  }
}

Once connected, Claude can call system_status, list_gitrepos, git_status, top_processes, and rag_query directly from any conversation — with every call logged to the audit trail.

📚 RAG Knowledge Base

The RAG layer ingests .txt, .md, .log, .py, .yaml, and .json files using a sliding-window chunker with upsert deduplication:

# Ingest an entire directory recursively
python main.py ingest C:\Gitrepos

# Ask the agent a RAG-grounded question
python main.py chat
> What does the ZKP-RA circuit enforce at the policy layer?

⚙️ Configuration

All behaviour is controlled by config.yaml — no code changes needed:

llm:
  model: "qwen2.5-coder:7b"   # swap to llama3.2, mistral, deepseek-r1, etc.
  temperature: 0.1             # low = more deterministic tool calls

rag:
  chunk_size: 512
  chunk_overlap: 64
  top_k: 5

security:
  max_file_size_mb: 100
  allowed_paths:
    - "C:\\Gitrepos"
    - "C:\\Users\\Sunil\\Documents"
  blocked_paths:
    - "C:\\Windows\\System32"
  require_approval_for:
    - "rm"
    - "Remove-Item"

monitoring:
  alert_cpu_percent: 90
  alert_memory_percent: 85
  alert_disk_percent: 80

📁 Project Structure

LaptopAI-Agent/
├── main.py                        # CLI entry point
├── config.yaml                    # All runtime configuration
├── requirements.txt
├── src/
│   ├── agent/
│   │   ├── graph.py               # LangGraph StateGraph — agent ↔ ToolNode loop (max 10 iters)
│   │   └── tools.py               # LangChain @tool definitions + PermissionGuard hooks
│   ├── mcp/
│   │   └── server.py              # MCP stdio server — 5 tools exposed to Claude
│   ├── rag/
│   │   └── knowledge_base.py      # ChromaDB ingestion + cosine semantic query
│   └── security/
│       ├── audit.py               # SHA-256 chained append-only audit logger
│       └── permissions.py         # PermissionGuard — path, command, size enforcement
├── data/
│   └── chroma_db/                 # Local vector store (gitignored)
└── logs/
    └── audit.jsonl                # Tamper-evident audit trail (gitignored)

🔬 Recommended Local Models

ollama pull qwen2.5-coder:7b   # recommended
ollama pull llama3.2:3b        # lightweight alternative

📦 Key Dependencies

📖 Research & References

👤 Author

Sunil Gentyala
Lead Cybersecurity and AI Security Consultant — HCL America Inc., Dallas TX
IEEE Senior Member No. 101760715 · CISM No. 263076408 · MBCS · ACM Professional Member · CIISec Affiliate

📄 License

Apache 2.0 — See LICENSE for details.