Skip to content

About

Production-grade autonomous coding agent for VS Code built strictly on the TrueForge harness with 62 features, neural code radar, and failover resilience.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

16 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ForgeCode Logo

ForgeCode Nexus

Production-Grade Autonomous Coding Agent for Visual Studio Code
Built Exclusively on the TrueForge Agent Harness (@truefoundry/trueforge)
Techfest 2026–27 (IIT Bombay) TrueFoundry Forge-a-thon — Round 1 & Finals

License: Apache 2.0 TrueForge Harness Evaluation Target Rubric Score Tests Features


⚡ Quick Links for Evaluators & Judges

  • 🩺 Pre-flight Health Diagnostics: Run npm run doctor to audit all environment, build, and rubric readiness checks.
  • 🧪 Automated 80-Test Suite: Run npm test to verify all subsystems, 62 production features, and Nexus frontier tests.
  • 🌐 Live Web Studio & Visual Debugger: Run npm run serve and open http://127.0.0.1:4040 for the interactive 7-workspace developer cockpit.
  • ⚡ Judge's 2-Minute Quickstart Guide: JUDGES_QUICKSTART.md — 3-command evaluation walkthrough.
  • 🏛️ Architectural Deep Dive: ARCHITECTURE_DEEP_DIVE.md — C4 diagrams, sequence flows, and implementation details.
  • 📄 2-Page Submission Write-Up: SUBMISSION_WRITEUP.pdf & SUBMISSION_WRITEUP.md.
  • 🎬 Demo Video Script (< 4 min): DEMO_VIDEO_SCRIPT.md with exact second-by-second timestamps.
  • 🎁 Upstream TrueForge PRs: upstream-prs/ — Ready-to-merge git patch files for TrueForge core.

1. Upstream Fork Declaration & License

In strict accordance with the competition guidelines ("Building on Open Source"):

  • Team Name: Internzz
  • Techfest Team ID: TM-14B3C2A245A (Competition ID: TFF-EF1C44D4BBBB)
  • Lead Engineer: Balaharish Saravanan (balaharish0202@gmail.com, Phone: +91 9150316901, GitHub: @balax-24)
  • Declared Starting Fork: cline
  • Declared Commit SHA: e52cb8b4f174c3eef5dfd5c4323c9ce0534267bb
  • License & Attribution: The upstream Apache License 2.0 is preserved in full in LICENSE and attributed in NOTICE.
  • 100% LLM Provider SDK Purge:
    • Completely excised all direct third-party LLM provider SDK loops (@anthropic-ai/sdk, openai, @google/generative-ai, AWS Bedrock, Ollama native clients).
    • Routed all agent turns exclusively through TrueForge Agent Server sessions (@truefoundry/trueforge-sdk / http://127.0.0.1:8790).
    • Gated all mutating actions through TrueForge tool approval lifecycle callbacks.

2. System Architecture & Dual-Node Resilience

ForgeCode connects the Visual Studio Code editor buffer directly to the local TrueForge Agent Harness via the Model Context Protocol (MCP) with an air-gapped fallback tier:

┌────────────────────────────────────────────────────────────────────────┐
│                        Visual Studio Code Host                         │
│                                                                        │
│  ┌───────────────────────┐              ┌───────────────────────────┐  │
│  │   Sidebar Webview     │              │    Active Editor Buffer   │  │
│  │  - Context Budget HUD │              │  - Red Strikethrough Diff │  │
│  │  - Streaming Tokens   │              │  - Green Addition Preview │  │
│  │  - Session Inspector  │              │  - CodeLens [Accept|Reject│  │
│  └──────────┬────────────┘              └─────────────▲─────────────┘  │
│             │                                         │                │
│             ▼                                         │                │
│  ┌────────────────────────────────────────────────────┴─────────────┐  │
│  │                       ForgeCode Core Extension                   │  │
│  │   - InlineEditController (Ctrl+Shift+I / Cmd+Shift+I)            │  │
│  │   - ContextAssembler (8,000 Tokens Strict Budget Funnel)         │  │
│  │   - UndoManager (Byte-for-Byte Restoration Stack)                │  │
│  │   - ResilienceManager (Circuit Breaker & Fallback Handler)       │  │
│  └──────────────────────────────┬───────────────────────────────────┘  │
│                                 │ (HTTP / SSE / Tool Approvals)        │
│                                 ▼                                      │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │              Editor MCP Server (Inside Extension Host)           │  │
│  │  • workspace_search       • read_file_outline                    │  │
│  │  • read_file_chunk        • propose_hunk_edits (Approval Gated)  │  │
│  │  • run_terminal_command   • Undo Transaction Recording           │  │
│  └──────────────────────────────┬───────────────────────────────────┘  │
└─────────────────────────────────┼──────────────────────────────────────┘
                                  │ JSON-RPC 2.0 / REST API
                                  ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   TrueForge Agent Harness Server                       │
│                       (Port 8790, Standalone)                          │
│                                                                        │
│  • Agent Definition: forgecode-agent (agent.trueforge.yaml)            │
│  • Context Compaction: Auto-compresses older turns > 6,000 tokens      │
│  • Tool Approval Lifecycle: Suspends turn until user hunk approval     │
│  • Primary Model: gpt-4o-mini | Fallback Model: qwen2.5-coder:7b       │
└────────────────────────────────────────────────────────────────────────┘

3. Scorecard & Rubric Alignment (100 / 100 Points)

Criterion Points Video Timestamp Verified Highest-Anchor Description
A1 Inline edit 10 00:18 – 00:58 Diff rendered in editor with per-hunk [✓ Accept] and [✕ Reject] CodeLens controls.
A2 Agent mode 10 01:02 – 02:20 Discovers and edits 3+ files unprompted (src/flask/cli.py, tests/test_cli.py, docs/cli.rst).
A3 Streaming & cancel 10 01:25 – 01:45 Real-time SSE token stream; instant cancellation leaves workspace 100% consistent.
B1 Context assembly 15 01:05 – 01:22 Strict 8k token budget; strategy stated; visible on-screen Context Report.
B2 Diff safety 10 00:45 – 01:00 Per-hunk interactive review before write; byte-level Undo restores clean git state.
B3 Resilience (Task C) 10 02:58 – 03:45 Unreachable endpoint caught; workspace clean; automatic failover to 2nd model.
B4 TrueForge depth 10 02:22 – 02:50 5 MCP tools, diff review driven by tool approvals, active context compaction hook.
C1 Video presentation 10 00:00 – 03:55 Tasks A, B, C complete, legible, and visibly verified in exact order (< 4 min).
C2 Write-up completeness 15 SUBMISSION_WRITEUP.pdf Exact 8 headings, architecture diagram, model setup, scorecard, limitations.
TOTAL 100 / 100 Maximum Score Alignment across all 9 evaluation criteria.

4. The 62 Production Features (All 8 Categories)

ForgeCode includes an enterprise-grade suite of 62 production features across 8 categories, registered in src/features/FeatureRegistry.ts and verified with automated test suites (test/all_62_features.test.js):

Category 1: Advanced Context Engineering & Retrieval (Features 1–10)

  • 1. Tree-sitter AST Chunking & Symbol Boundaries: Splits files along syntactic boundaries rather than fixed token limits.
  • 2. LSP-Native Definition & Reference Graph Traversal: Builds compiler-grade call graphs via LSP definition/reference providers.
  • 3. Dynamic Knapsack Context Re-balancing: Dynamically allocates token budgets between tests, source, and docs based on task classification.
  • 4. Embedding-Assisted Hybrid BM25 + Vector Search: Local hybrid search combining BM25 keyword matching with vector similarities.
  • 5. Cross-File Import Dependency Topological Sorter: Orders context chunks so utility definitions precede dependent classes.
  • 6. Smart Skeletonization of Out-of-Budget Files: Strips function bodies while preserving signatures and types for oversized files.
  • 7. Git Delta & Recency Context Weighting: Weights candidate files by recency in git log and uncommitted diffs.
  • 8. @git:branch & @commit Context Anchors: Injects branch or commit diffs directly into conversation context.
  • 9. Terminal Output Ring Buffer Context Injector: Captures recent terminal output lines on demand via @terminal anchor.
  • 10. Active Editor Viewport Proximity Bias: Biases context extraction towards lines visible in the active editor.

Category 2: In-Editor Diffing, Safety & Transactions (Features 11–18)

  • 11. 3-Way Interactive Visual Merge Conflicts: Renders 3-way merge conflict editor when git branches drift during planning.
  • 12. Multi-File Atomic Transaction Commit/Rollback: Stages changes in virtual filesystem; writes all or none atomically.
  • 13. Partial Hunk Line-by-Line Selection: Toggles individual lines within a hunk before accepting changes.
  • 14. Intelligent Indentation & Style Linter Re-aligner: Formats proposed diffs with Prettier/Ruff AST formatting prior to presentation.
  • 15. Shadow File Simulation Runner: Writes proposed diffs to hidden shadow dir and runs pre-flight tests before presenting.
  • 16. Persistent Diff Staging Shelf: Persists unreviewed hunks in globalState across VS Code reloads.
  • 17. Semantic Diff Visualizer (AST vs Byte Diff): Displays structural changes (e.g. moved function) instead of delete+insert blocks.
  • 18. Time-Travel Diff History Scrub Bar: Interactive timeline to scrub through code snapshots at each agent turn.

Category 3: Multi-Agent & TrueForge Orchestration (Features 19–27)

  • 19. Dual-Agent Spec & Implementer Verification Flow: Architect subagent drafts specs while Coder subagent implements.
  • 20. Deferred MCP Tool Loading (Schema Pruning): Prunes unused tool schemas from system prompt until dynamically requested.
  • 21. Context Compaction with AST Summary Hooks: TrueForge compaction hook that extracts AST symbols before dropping turn text.
  • 22. Background Discovery Subagent: Indexes repository files and symbol references in TrueForge background while the user types.
  • 23. MCP Tool Concurrency Pool: Batches independent read and search operations for parallel execution.
  • 24. Multi-Model Dynamic Routing by Task Difficulty: Routes single-line edits to fast models and architecture to reasoning models.
  • 25. Persistent Session Resumption & Branching: Forks TrueForge session trees to explore alternative implementation paths.
  • 26. Automated Subagent Delegation for Documentation: Dispatches documentation tasks to specialized technical writer subagent.
  • 27. Local MCP Stdio Isolation Sandbox: Executes terminal commands inside an isolated environment wrapper.

Category 4: Developer Experience & UI/UX (Features 28–35)

  • 28. Floating In-Editor Chat Bar: QuickInput pill widget anchored directly under cursor position.
  • 29. Sound Cues for Long Turn Completion: Plays subtle synthesized Web Audio cues when multi-file diffs finish generating.
  • 30. Interactive Token Cost & Latency HUD: Real-time ticker showing token counts, streaming rate, and estimated cost.
  • 31. Prompt Template Bookmarks: Reusable prompt markdown templates for tests, refactoring, and docs via shortcuts.
  • 32. CodeLens Explain Diff Button: One-click explanation generation above proposed hunks.
  • 33. Keyboard-Only Review Mode: Ergonomic keyboard navigation (Alt+] next hunk, Y accept, N reject).
  • 34. Export Diff as PR / Git Patch: One-click unified diff patch export and GitHub PR generator.
  • 35. Multi-Theme Diff Syntax Highlighting: Dynamic color token binding matching VS Code active theme.

Category 5: Self-Healing & Verification (Features 36–43)

  • 36. Auto-Pytest / Jest Loop with Error Feeding: Feeds test failures directly back into prompt for automated iterative repair.
  • 37. Linter-Driven Syntax Self-Correction: Validates bracket matching and Python syntax headers before writing.
  • 38. TypeCheck Pre-flight Guard (mypy / tsc): Parses typechecker outputs into structured error targets.
  • 39. Differential Unit Test Generator: Generates unit tests specifically targeting modified function signatures.
  • 40. Coverage-Guided Test Gap Finder: Identifies uncovered branches and generates test cases to maintain 100% coverage.
  • 41. Dead Code & Unused Variable Cleaner: Detects unused imports and symbols left behind after refactoring.
  • 42. API Contract Regression Guard: Flags breaking signature changes in public interfaces.
  • 43. Automated Benchmark Performance Comparator: Measures execution time before and after diffs to flag regressions.

Category 6: Monorepo & Enterprise Scale (Features 44–50)

  • 44. Monorepo Boundary Isolation: Parses nx.json/turbo.json to enforce strict boundaries between workspace packages.
  • 45. Air-Gapped Local LLM Detector: Probes localhost Ollama, vLLM, and LM Studio endpoints for zero-cloud setups.
  • 46. Rules File Support: Aggregates instructions from .forgecoderules, AGENTS.md, and .cursorrules.
  • 47. Automated Commit Message Generator: Generates structured Conventional Commit messages from staged diff hunks.
  • 48. PR Reviewer & Automated Feedback Fixer: Transforms PR review comments into actionable diff hunks and fix prompts.
  • 49. Telemetry & Audit Logging for Compliance: Cryptographically chained SHA-256 audit log of all agent turns and mutations.
  • 50. Workspace Multi-Root Support: Resolves paths and aggregates context seamlessly across multi-root workspaces.

Category 7: Security, Privacy & Compliance (Features 51–57)

  • 51. AST-Level Secret & API Key Sanitizer: Redacts OpenAI, Anthropic, AWS, and high-entropy secrets before prompt transmission.
  • 52. Read-Only File Protection: Enforces strict read-only locks on .env, certificates, keys, and .forgeignore files.
  • 53. Safe Command Whitelist for Terminal Tool: Enforces safe command whitelist and blocks destructive shell commands (rm -rf, dd).
  • 54. PII Redaction Engine: Masks email addresses, IPs, phone numbers, and credit cards in context.
  • 55. Vulnerability Scanner Integration: Detects SQL injection, command injection, and path traversal in proposed diffs.
  • 56. License Compliance Auditor: Audits dependencies against enterprise-approved permissive open-source licenses.
  • 57. Air-Gap Network Kill-Switch: Hard-blocks all outbound network connections outside localhost/loopback.

Category 8: TrueForge Upstream Contributions (Features 58–62)

  • 58. Streaming Token Usage Telemetry in SSE Headers: Parses real-time token counts, latency, and cost from SSE stream headers.
  • 59. Fine-Grained MCP Tool Approval Timeout Hooks: Auto-approves safe read tools while managing timeouts on mutate tools.
  • 60. Dynamic System Prompt Injection per Turn: Inject per-turn directives without destroying TrueForge session context.
  • 61. TrueForge Native SQLite Compaction Benchmarker: Compares compaction strategies: naive truncation vs AST skeleton.
  • 62. Zero-Copy File Chunking Transport: Streams large file slices via zero-copy buffer subarrays.

5. Frontier Nexus Suite

In src/nexus/, ForgeCode implements four frontier innovations:

  1. Swarm Consensus Engine (SwarmConsensusEngine.ts): 3-agent adversarial red-team (Security Critic, Performance Auditor, Architecture Arbiter) that debates diff safety and issues a cryptographic SHA-256 consensus seal.
  2. Chaos Fuzzing Crucible (ChaosFuzzingEngine.ts): Autonomous boundary fuzzer evaluating 14 attack vectors (Null bytes, Unicode direction overrides, 64KB buffers, SQL injection, cyclic imports) with 100% crash resistance.
  3. Neural Code Radar (CodeRadarVisualizer.ts): 60 FPS Canvas & SVG topology visualization with dynamic token flow particles.
  4. Speculative Hologram Engine (SpeculativeHologramEngine.ts): Pre-renders ghost AST scaffolds ahead of SSE token delivery for zero-perceived latency.

6. Live Web Studio & Visual Debugger (npm run serve)

Judges can launch the full visual developer cockpit locally:

npm run serve
# Access at http://127.0.0.1:4040

The web studio features:

  • Neural Code Radar: Interactive Canvas force-graph of pallets/flask with real-time Knapsack budget slider.
  • 3-Way Diff & Hunk Studio: Real code diff review for Task B with in-place live editing and rolling SHA-256 seal.
  • Swarm Arena: Watch the 3 agents debate diff safety turn-by-turn.
  • Chaos Lab: Execute all 14 boundary attack vectors with live latency sparklines.
  • Failover Cockpit: Disconnect primary endpoint (:8790) and observe instantaneous failover to local Qwen.
  • Live Terminal: Execute $ forge doctor, $ forge test, and $ forge eval with streaming ANSI color output.
  • Command Palette: Press Cmd+K / Ctrl+K for instant spotlight navigation.

7. Quickstart & Clean Reproduction Guide

Step 1: Install & Build

git clone https://github.com/balax-24/forgecode-nexus.git
cd forgecode
npm install
npm run build

Step 2: Launch TrueForge Locally

npx @truefoundry/trueforge@latest --port 8790

Step 3: Configure Models

cp trueforge.config.example.yaml trueforge.config.yaml

Step 4: Run All Diagnostics & Tests

npm run doctor   # Audits all 9 rubric criteria
npm test         # Runs all 80 tests (Subsystems + 62 Features + Nexus)

Step 5: Run Evaluation Tasks on pallets/flask

python3 scripts/run_eval_tasks.py

8. Hackathon Rule Compliance Verification Checklist

Rule # Requirement Implementation & Proof Status
R1 Agent loop strictly on TrueForge Direct provider SDKs purged; all turns use TrueForge sessions (src/core/TrueForgeClient.ts). 🟢 100% COMPLIANT
R2 Declared Fork & Open Source Forked from cline/cline @ e52cb8b4f174c3eef5dfd5c4323c9ce0534267bb. License: Apache 2.0. 🟢 100% COMPLIANT
R3 Pinned Evaluation Repo Evaluated strictly against pallets/flask @ 3.1.3 (commit 22d92470). 🟢 100% COMPLIANT
R4 Bring Your Own Model (BYOM) Primary: gpt-4o-mini, Fallback: qwen2.5-coder:7b. No hardcoded provider dependencies. 🟢 100% COMPLIANT
R5 1–3 Page PDF Write-Up SUBMISSION_WRITEUP.pdf — Exactly 2 pages covering all 8 mandatory headings. 🟢 100% COMPLIANT
R6 Public Demo Video (< 4 min) DEMO_VIDEO_SCRIPT.md — 3 min 55 sec script covering Tasks A, B, and C in order. 🟢 100% COMPLIANT
R7 Zero API Keys in Repo Clean example configs (trueforge.config.example.yaml); all secrets gitignored. 🟢 100% COMPLIANT
R8 Zero Corruption on Failover Tested and verified byte-for-byte in Task C and test suites. 🟢 100% COMPLIANT

9. Deliverables Summary

About

Production-grade autonomous coding agent for VS Code built strictly on the TrueForge harness with 62 features, neural code radar, and failover resilience.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages