An autonomous agentic IDE where agents never read raw code. Every structural element is a devtag. Every plan element is a plantag. Every edit operation is a buildtag. The system improves itself.

Personal IDE is a fully self-modifying, agent-driven development environment built on a unified tag language. It operates across two concurrent layers:

Build Layer — Runs build cycles: pre-edit crawls, Waiting state, Skeptic refinement, Command voting, Builder execution, post-commit validation.

Meta Layer — Runs persistently: the Blame Crawler attributes outputs to models, Gap Analysis identifies systemic failures, the Suggested Jobs system generates improvement work, and THE GOD FACTORY Agent synthesizes everything into a conversational self-improvement loop.

These two layers share one forensic database, one tag registry, and one agent authority system.

Windows (PowerShell):

git clone https://github.com/Ileices/personal_IDE.git
cd personal_IDE
.\setup.ps1

Linux / macOS:

git clone https://github.com/Ileices/personal_IDE.git
cd personal_IDE
chmod +x setup.sh && ./setup.sh

Or manually:

git clone https://github.com/Ileices/personal_IDE.git
cd personal_IDE
pnpm install              # install all dependencies
pnpm --filter @personal-ide/shared build   # build the shared types package
cp .env.example .env      # then edit .env and add your GITHUB_PAT

npm run dev

This starts:

• Server at http://localhost:3001 (Fastify + API routes)
• Frontend at http://localhost:5173 (React + Vite)

Open http://localhost:5173 in your browser.

The Help system is now an executable roadmap.

Accessible via the Help icon (Activity Bar, bottom left) or ? keyboard shortcut:

• Full-Text Search: Searches section titles, summaries, all detail content, tags, and quick tips — not just titles
• Tag Navigation: Sections tagged with feature names, pipeline membership (build-layer, meta-layer, nano-sea-v2), and status (coming-soon, active)
• Cross-References: Each section links to related panels and forensic database entries

The Help system marks unimplemented specification concepts with status coming_soon:

• Build Layer: WAITING state machine 5-state diagram, voting rules detail, tag validator 5-check spec, pre-edit protocol detail
• Meta Layer: Blame Record full schema (25+ fields), Model Registry capability profiles, quality dimensions 7-dimension scoring formulas, Tool Criticism 3-trigger rule, tool modification schema
• God Factory: Interactive state routing, 6 background scan sub-agents + schedules, 6 idle suggestion categories, 8 screen panels detail, complete authority boundary list (may/may not)
• Gap Analysis: 5 anti-patterns (AI Slop, Drift, Spaghetti Growth, Hallucination Loop, Context Loss), debt score formula (step-by-step), 15 deterministic callable tools, 7 agent performance metrics
• Project State Crawler: Tree-sitter parsing layer full mapping, sub-crawler architecture + skip rules, 4 drift types with escalation triggers, WAITING reconciliation rules
• Suggested Jobs: 10 codebase review protocols in sequence, full job record schema (20+ fields), sandbox 5-sub-agent loop, 6-stage implementation pipeline with crash recovery
• Unified Spec: Complete 80+ devtag base vocabulary, voting and command agent decision rules, output capture layer mechanism, unified spec integration points
• Memory: Six dedicated memory surfaces (Ask/Edit/Plan × Chat/Agent Loop) as first-class UI panels
• Nano Sea v2: Architecture map, swarm layer visualizer, cosmic cycle timeline, RBY-simplex navigator

These "coming soon" items serve two purposes:

1. User expectations: Users know what's planned and can navigate to related implemented features
2. Implementation roadmap: Engineers can use tags to identify features ready for surgical implementation

All 12 specification documents in build_runs/feedback/ are now fully covered by the Help system:

• unifi_spec.txt — Unified Build Layer + Meta Layer architecture
• the_god_factory_agent.txt — God Factory interactive + background scan states
• memory_tab_spec.txt — Six dedicated memory surfaces + 9 agents + scope enforcement
• suggested_jobs_system.txt — Blame-driven crawler + 10 protocols + sandbox pipeline
• forensic_database_blame_crawler.txt — Blame records, quality dimensions, tool criticism
• gap_analysis_system.txt — 5 gap agents, drift types, forensic outputs
• project_state_crawler.txt — Ground truth, drift detection, WAITING integration
• Plus 5 additional specification documents on nano sea, midwife, deployment, security, and training

See NANO_train/NANO_corpus/lump/NERDS_ASSEMBLE.txt for the comprehensive Nano Sea v2 alignment document written for engineers:

• 30 validated experiments proving soft-k routing outperforms hard top-k by 8-10%
• Swarm layer mechanics and chromatic index routing (RBY-simplex) explanation
• Cosmic cycles and deposit-guided warm-start (+25% convergence improvement)
• Integration into agent query routing with blame feedback loop
• 6-phase build order and anti-patterns guide
• Q&A and vision statement for the future nano sea

personal_IDE/
├── apps/
│   ├── server/          # Fastify backend — chat, models, memory, agent, nano control
│   └── web/             # React frontend — Vite, Tailwind, Monaco editor
├── packages/
│   └── shared/          # Shared TypeScript types & constants (compiled to dist/)
├── NANO_train/          # Sea of Nanos — Python ML backend
│   ├── main.py          # Boot sequence (10 steps)
│   ├── core/            # Foundation nanos
│   ├── nanos/           # 296 specialized nanos (19 categories)
│   ├── mesh/            # P2P networking, global pool, peer discovery
│   ├── server/          # FastAPI backend (port 5100)
│   ├── training/        # Training pipeline
│   └── scanner/         # AE filesystem scanner
├── scripts/
│   └── setup.js         # Cross-platform setup script
├── setup.sh             # Unix setup wrapper
├── setup.ps1            # Windows setup wrapper
└── .env.example         # Environment template

Agents never read raw code. Every structural element is represented as a tag, resolved through a deterministic tool call.

A buildtag is invalid unless it references at least one existing devtag and at least one unfulfilled plantag.

• Base vocabulary — module, class, function, method, import, route, schema, component, service, test, and 70+ more
• Relationship tags — calls, inherits, implements, composes, depends_on, subscribes_to, publishes, reads_from, writes_to
• Nano Sea tags — nano:module, nano:layer, nano:node, nano:weight:frozen, nano:weight:personal, nano:cycle
• Attribution tags — agent_generated, human_generated, last_modified_by, created_by, reviewed_by
• Performance tags — perf_critical, memory_bound, hot_path, latency_sensitive, cpu_bound
• Versioning tags — version, deprecated, breaking_change, stable, legacy, public_api
• Status markers — needs_rollback, needs_refactor, needs_test, dead_code, orphaned

resolve_devtag(tag)   // → file, line range, parent, relationships, content hash
resolve_plantag(tag)  // → status, requires[], produces[], milestone, estimate
resolve_buildtag(tag) // → operation type, source devtag, target devtag, status

The full tag chart is a tool call, not a prompt. Zero context tokens consumed.

Primary interface. All panels are collapsible in the right sidebar.

The God Factory chat agent has direct access to every system API:

# Codebase tools
list_files, read_file, search_code, get_docs, patch_file, write_file, run_command

# God Factory system
get_notification_queue, get_idle_suggestions, create_brainstorm_job

# Suggested Jobs
find_suggested_jobs, get_job_detail, read_sandbox_status, implementation_pipeline_status

# Forensic tools
read_forensic_entries, read_blame_records, regression_index

# Live analysis
live_debt_check, live_coverage_check, live_pattern_query, debt_heatmap, pattern_trend

# Tag system
inspect_devtag, resolve_devtag, tag_vocabulary_diff, orphan_scan, conflict_scan

# Gap analysis
gap_scan, agent_conformance_report

# Authority
spawn_authority_check

Three sub-agents run concurrently. No edit begins until all three deliver outputs to WAITING state:

1. Memory Crawler — All accessible memory → compact devtag database
2. Project Description Crawler — All project files → plantag database
3. Project State Crawler — Actual files on disk → ground truth devtag snapshot + drift events

CRAWLING → TAG_GENERATION → REFINING → VOTING → SENT_TO_COMMAND

Skeptic Agent refinement: max 5 iterations. Tie votes → Command Agent at weight 1.5. God Factory holds absolute veto.

1. Integration Verification Sub-Agent
2. Regression Sub-Agent
3. Version Control Agent
4. Coverage Analysis Agent
5. Blame Crawler (async)

1. Pre-Implementation Scan — Ground truth vs sandbox drift check
2. Backup — Version Control rollback point tagged with job_id
3. Staged Rollout — One atomic step at a time, full pre-edit protocol each
4. Live Testing — Full test suite against real codebase
5. Stability Check — 10-cycle monitoring window, auto rollback on crash
6. Completion — Job marked implemented, commits tagged, plantags done

Every model output produces a blame record. No output is unattributed. The output capture layer introduces zero latency.

Quality dimensions (composite score = weighted average):

Composite score < 0.65 for 3 consecutive outputs → Tool Criticism sub-agent activates, generates improvements forwarded to Suggested Jobs.

Persistent systemic analysis across all cycles, agents, forensic history, and sessions. Five gap categories: coverage, structural, process, tag system, agent performance.

+1  needs_refactor    +2  needs_test       +1  dead_code
+3  circular_dep      +2  spaghetti_index  +5  regression (cause in this file)
-1  test coverage     -1  plantag:done

Files exceeding their debt ceiling are excluded from build step assignments. Override: God Factory Agent only.

45 forensic tables. No entries may ever be deleted.

Sub-agents: Diff, Conflict, Regression, Dead Tag, Context Window Manager, Integration Verification

The Nano Sea is a distributed mesh of ultra-small ML models operating as a compute layer.

• 296 nano models trained for specialized sub-tasks
• Mesh networking, P2P peer discovery, global compute pool
• Training pipeline managed by Midwife Bird-Feeding agent
• Every nano operation represented in devtag:nano taxonomy

cd NANO_train && python main.py

Copy .env.example to .env:

Copy .env.example to .env and configure:

The shared package needs to be compiled. Run:

pnpm --filter @personal-ide/shared build

The server auto-detects Python. It tries python, python3, and py -3 (Windows). Make sure Python 3.10+ is on your PATH.

Kill the process on port 3001 or 5173, or change SERVER_PORT in .env.

Private — All rights reserved.