gencode-ai 0.1.0

package/docs/proposals/research/claude-code-research.md

@@ -0,0 +1,307 @@
+# Claude Code Research Summary
+
+This document preserves research findings from analyzing Claude Code's implementation, used to inform mycode's enhancement proposals.
+
+## Table of Contents
+
+1. [Memory System Research](#1-memory-system-research)
+2. [Context Management Research](#2-context-management-research)
+3. [Session Management Research](#3-session-management-research)
+4. [Cross-Tool Comparison](#4-cross-tool-comparison)
+5. [References](#5-references)
+
+---
+
+## 1. Memory System Research
+
+### CLAUDE.md File Hierarchy
+
+Claude Code uses a **4-level hierarchical memory system** (lowest to highest priority):
+
+| Level | Location | Purpose | Version Control |
+|-------|----------|---------|-----------------|
+| 1. User/Global | `~/.claude/CLAUDE.md` | Personal preferences across all projects | Personal, not shared |
+| 2. Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared project standards | Checked into git |
+| 3. Rules | `./.claude/rules/*.md` | Modular rule organization | Checked into git |
+| 4. Enterprise | Organization-defined location | Organization-wide policies | Managed by org |
+
+### /init Command Internal Mechanism
+
+The /init command uses a two-part system:
+
+**1. Context Gathering Phase** - Uses BatchTool with GlobTool:
+```json
+{
+  "type": "tool_use",
+  "name": "BatchTool",
+  "input": {
+    "description": "Gather repository information",
+    "invocations": [
+      { "tool_name": "GlobTool", "input": { "pattern": "package*.json" } },
+      { "tool_name": "GlobTool", "input": { "pattern": "*.md" } },
+      { "tool_name": "GlobTool", "input": { "pattern": ".cursor/rules/**" } },
+      { "tool_name": "GlobTool", "input": { "pattern": ".cursorrules/**" } },
+      { "tool_name": "GlobTool", "input": { "pattern": ".github/copilot-instructions.md" } }
+    ]
+  }
+}
+```
+
+**2. Generation Phase** - Uses this prompt (384 tokens):
+```
+Please analyze this codebase and create a CLAUDE.md file, which will be
+given to future instances of Claude Code to operate in this repository.
+
+Include:
+1. Commands that will be commonly used, such as how to build, lint, and
+   run tests. Include the necessary commands to develop in this codebase,
+   such as how to run a single test.
+
+2. High-level code architecture and structure so that future instances
+   can be productive more quickly. Focus on the "big picture" architecture
+   that requires reading multiple files to understand.
+
+Guidelines:
+- If there's already a CLAUDE.md, suggest improvements to it.
+- Do NOT repeat obvious instructions like "Write unit tests for all new
+  utilities" or "Never include sensitive information in code".
+- Do NOT list every component or file structure that can be easily discovered.
+- If there is a README.md, include the important parts.
+- Do NOT make up sections like "Tips for Development" unless this is
+  expressly included in other files.
+- If there are Cursor rules (.cursor/rules/ or .cursorrules) or Copilot
+  rules (.github/copilot-instructions.md), make sure to include them.
+
+The file must begin with:
+"This file provides guidance to Claude Code (claude.ai/code) when working
+with code in this repository."
+```
+
+### Context Injection Method
+
+**Critical Finding**: Memory content is NOT directly prepended to the system prompt.
+
+Instead, Claude Code uses a specific pattern:
+1. Memory content is wrapped in `<system-reminder>` tags
+2. Placed as the **first user message** in the conversation (after system prompt)
+3. Includes explicit instruction that content "may or may not be relevant"
+
+```xml
+<system-reminder>
+As you answer the user's questions, you can use the following context:
+# claudeMd
+Codebase and user instructions are shown below. Be sure to adhere to these instructions.
+IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.
+
+Contents of /path/to/CLAUDE.md (project instructions, checked into the codebase):
+
+[CLAUDE.md content here]
+
+IMPORTANT: this context may or may not be relevant to your tasks.
+You should not respond to this context unless it is highly relevant to your task.
+</system-reminder>
+```
+
+### Import Syntax Rules
+
+- Syntax: `@path/to/file` at beginning of a line
+- Supports relative paths, absolute paths, and `~` expansion
+- Max import depth: 5 levels (prevents circular references)
+- Imports are NOT evaluated inside markdown code blocks or inline code spans
+- Imported files can recursively import other files
+
+### Size Limits
+
+| Metric | Recommended Limit |
+|--------|-------------------|
+| Total memory content | < 40,000 characters |
+| Warning threshold | ~44.7k characters |
+| Individual rule files | < 500 lines |
+
+---
+
+## 2. Context Management Research
+
+### Memory Tool API (Beta)
+
+Claude Code's Memory Tool (beta API `context-management-2025-06-27`) enables agents to store and retrieve information across conversations.
+
+**Commands:**
+
+| Command | Description | Input |
+|---------|-------------|-------|
+| `view` | Shows directory or file contents | `path`, optional `view_range` |
+| `create` | Creates a new file | `path`, `file_text` |
+| `str_replace` | Replaces text in file | `path`, `old_str`, `new_str` |
+| `insert` | Inserts at line | `path`, `insert_line`, `insert_text` |
+| `delete` | Deletes file/directory | `path` |
+| `rename` | Renames/moves file | `old_path`, `new_path` |
+
+**System Prompt Injection:**
+```
+IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
+MEMORY PROTOCOL:
+1. Use the `view` command of your `memory` tool to check for earlier progress.
+2. ... (work on the task) ...
+   - As you make progress, record status / progress / thoughts etc in your memory.
+ASSUME INTERRUPTION: Your context window might be reset at any moment, so you
+risk losing any progress that is not recorded in your memory directory.
+```
+
+### Context Editing Configuration
+
+```typescript
+context_management: {
+  edits: [
+    {
+      type: "clear_tool_uses_20250919",
+      trigger: {
+        type: "input_tokens",
+        value: 100000  // Trigger at 100K tokens
+      },
+      keep: {
+        type: "tool_uses",
+        value: 3  // Keep last 3 tool results
+      },
+      exclude_tools: ["memory"]  // Never clear memory operations
+    }
+  ]
+}
+```
+
+### Context Compaction SDK Configuration
+
+```typescript
+compaction_control: {
+  enabled: true,
+  context_token_threshold: 100000,  // Default: 100k tokens
+  summary_prompt: "Custom summary instructions...",
+  model: "claude-haiku-4-5"  // Use cheaper model for summarization
+}
+```
+
+**Threshold Guidelines:**
+
+| Threshold | Use Case |
+|-----------|----------|
+| Low (5k-20k) | Sequential entity processing with clear boundaries |
+| Medium (50k-100k) | Multi-phase workflows with fewer checkpoints |
+| High (100k-150k) | Tasks requiring substantial historical context |
+
+### Token Cost Analysis
+
+**Before (No Context Management):**
+
+| Turn | Input Tokens | Cost (Claude) |
+|------|--------------|---------------|
+| 1 | 1,000 | $0.003 |
+| 10 | 10,000 | $0.03 |
+| 25 | 50,000 | $0.15 |
+| 50 | 100,000 | $0.30 |
+| 100 | 200,000 | Context Error |
+
+**After (With Context Editing - 84% reduction):**
+
+| Turn | Input Tokens | Notes |
+|------|--------------|-------|
+| 1 | 1,000 | |
+| 10 | 10,000 | |
+| 25 | 50,000 | |
+| 50 | 30,000 | Cleared at turn 40 |
+| 100 | 40,000 | Cleared at turn 80 |
+
+---
+
+## 3. Session Management Research
+
+### Session Resume Options
+
+```bash
+claude -c              # Continue most recent conversation
+claude -r "abc123"     # Resume specific session by ID
+claude --resume        # Interactive conversation picker
+```
+
+### Fork Behavior
+
+| Behavior | `forkSession: false` (default) | `forkSession: true` |
+|----------|-------------------------------|---------------------|
+| **Session ID** | Same as original | New session ID generated |
+| **History** | Appends to original | Creates new branch from resume point |
+| **Original Session** | Modified | Preserved unchanged |
+
+### Permission Persistence
+
+File creation permissions, previously approved commands, and MCP servers enabled in the original session remain active when resuming.
+
+**Key Insight**: Permission decisions are session-scoped, not conversation-turn-scoped.
+
+### Todo Persistence
+
+Claude has access to a persistent todo list that survives:
+- Context compaction (included in summary)
+- Session resume
+- Multiple compaction cycles
+
+### Known Limitations
+
+From GitHub issue discussions:
+
+1. **Context Loss on Crash**: Unlike web chat, CLI sessions can lose context on interruption
+2. **Summary Quality Degradation**: Multiple compactions can cause "off the rails" behavior
+3. **Missing Debug Information**: Auto-compact summaries may omit critical debugging details
+
+---
+
+## 4. Cross-Tool Comparison
+
+### Memory/Rules Comparison
+
+| Feature | Claude Code | Cursor | GitHub Copilot | mycode (Target) |
+|---------|-------------|--------|----------------|-----------------|
+| **Config File** | `CLAUDE.md` | `.cursorrules` | `.github/copilot-instructions.md` | `MYCODE.md` / `CLAUDE.md` |
+| **User Global** | `~/.claude/CLAUDE.md` | `~/.cursor/rules/` | N/A | `~/.mycode/MYCODE.md` |
+| **Rules Directory** | `.claude/rules/` | `.cursor/rules/` | `.github/instructions/` | `.mycode/rules/` |
+| **Path Scoping** | `paths:` frontmatter | `globs:` frontmatter | `applyTo:` frontmatter | Add `paths:` |
+| **Quick Add** | `#` prefix | N/A | N/A | Add `#` prefix |
+| **AI Init** | `/init` with LLM | N/A | N/A | Add `--ai` flag |
+| **Import Syntax** | `@path/to/file` | N/A | N/A | Add `@path` |
+
+### Context Compaction Comparison
+
+| Tool | Trigger | Mechanism | Distinct Feature |
+|------|---------|-----------|------------------|
+| **Claude Code** | Manual `/compact` or auto at ~95% | LLM summary, fresh start | Custom instructions support |
+| **OpenAI Codex CLI** | Token threshold (180k-244k) | Summary + recent messages (~20k tokens) | Preserves recent messages alongside summary |
+| **OpenCode (SST)** | Auto on overflow | Summary marked as assistant message | Separate pruning of old tool outputs |
+| **Amp (Sourcegraph)** | Manual only | Fork, handoff, thread reference | Philosophy: "keep conversations short" |
+
+**Best Practice**: Trigger at 85-90% (earlier than Claude Code's 95%) with user warnings and disable options.
+
+---
+
+## 5. References
+
+### Official Documentation
+- [Claude Code Memory Documentation](https://code.claude.com/docs/en/memory)
+- [Session Management - Claude Docs](https://platform.claude.com/docs/en/agent-sdk/sessions)
+- [Automatic Context Compaction - Claude Cookbook](https://platform.claude.com/cookbook/tool-use-automatic-context-compaction)
+- [Memory Tool Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
+
+### Engineering Blog Posts
+- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+- [Using CLAUDE.MD Files](https://claude.com/blog/using-claude-md-files)
+
+### Community Resources
+- [Build your own /init command](https://kau.sh/blog/build-ai-init-command/)
+- [Reverse engineering Claude Code](https://kirshatrov.com/posts/claude-code-internals)
+- [The Complete Guide to CLAUDE.md](https://www.builder.io/blog/claude-md-guide)
+- [Claude Code System Prompts Repository](https://github.com/Piebald-AI/claude-code-system-prompts)
+- [Context Compaction Research](https://gist.github.com/badlogic/cd2ef65b0697c4dbe2d13fbecb0a0a5f)
+
+### GitHub Issues
+- [Local Session History and Context Persistence #12646](https://github.com/anthropics/claude-code/issues/12646)
+- [Persistent Memory Between Sessions #14227](https://github.com/anthropics/claude-code/issues/14227)
+- [Pre-Compact Auto-Save and Improved Summarization #13239](https://github.com/anthropics/claude-code/issues/13239)
+- [Path Resolution Issues #4754](https://github.com/anthropics/claude-code/issues/4754)

package/examples/agent-demo.ts

@@ -0,0 +1,115 @@
+/**
+ * Agent Demo - Demonstrates the full agent loop with tools
+ *
+ * Run with: npx tsx examples/agent-demo.ts
+ */
+
+import 'dotenv/config';
+import { Agent } from '../src/agent/index.js';
+import type { AgentEvent } from '../src/agent/types.js';
+import chalk from 'chalk';
+
+// Setup proxy if configured
+const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
+if (proxyUrl) {
+  const { setGlobalDispatcher, ProxyAgent } = await import('undici');
+  setGlobalDispatcher(new ProxyAgent(proxyUrl));
+  console.log(chalk.dim(`Using proxy: ${proxyUrl}\n`));
+}
+
+// Detect provider
+function getConfig() {
+  if (process.env.ANTHROPIC_API_KEY) {
+    return { provider: 'anthropic' as const, model: 'claude-sonnet-4-20250514' };
+  } else if (process.env.OPENAI_API_KEY) {
+    return { provider: 'openai' as const, model: 'gpt-4o' };
+  } else if (process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY) {
+    return { provider: 'gemini' as const, model: 'gemini-2.0-flash' };
+  }
+  throw new Error('No API key found. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY');
+}
+
+async function main() {
+  console.log(chalk.cyan.bold('\n╭─────────────────────────────────────╮'));
+  console.log(chalk.cyan.bold('│') + '  ' + chalk.white.bold('Recode Agent Demo') + '                  ' + chalk.cyan.bold('│'));
+  console.log(chalk.cyan.bold('╰─────────────────────────────────────╯\n'));
+
+  const config = getConfig();
+  console.log(chalk.blue('ℹ') + ` Provider: ${chalk.bold(config.provider)} | Model: ${chalk.bold(config.model)}`);
+  console.log(chalk.blue('ℹ') + ` Working directory: ${chalk.dim(process.cwd())}\n`);
+
+  const agent = new Agent({
+    ...config,
+    cwd: process.cwd(),
+    maxTurns: 10,
+  });
+
+  // Auto-approve all tools for demo (no confirmation prompts)
+  agent.setConfirmCallback(async (tool, input) => {
+    console.log(chalk.yellow('⚡') + ` Auto-approved: ${chalk.bold(tool)}`);
+    return true;
+  });
+
+  // Demo prompt - ask agent to explore the project
+  const prompt = `Please explore this project and tell me:
+1. What is the project structure?
+2. What are the main source files?
+3. Give me a brief summary of what this project does.
+
+Use the Glob and Read tools to explore.`;
+
+  console.log(chalk.blue('▶ User:'));
+  console.log(chalk.white('  ' + prompt.split('\n').join('\n  ')));
+  console.log();
+
+  let responseText = '';
+
+  // Run the agent
+  for await (const event of agent.run(prompt)) {
+    switch (event.type) {
+      case 'text':
+        responseText += event.text;
+        break;
+
+      case 'tool_start':
+        console.log(chalk.magenta('⚙ Tool:') + ` ${chalk.bold(event.name)}`);
+        const inputStr = JSON.stringify(event.input);
+        console.log(chalk.dim('  Input: ' + inputStr.slice(0, 80) + (inputStr.length > 80 ? '...' : '')));
+        break;
+
+      case 'tool_result':
+        const status = event.result.success ? chalk.green('✓') : chalk.red('✗');
+        console.log(status + chalk.dim(` ${event.name} completed`));
+        // Show first few lines of output
+        const lines = event.result.output.split('\n').slice(0, 5);
+        for (const line of lines) {
+          console.log(chalk.dim('  │ ') + line.slice(0, 80));
+        }
+        if (event.result.output.split('\n').length > 5) {
+          console.log(chalk.dim('  │ ...'));
+        }
+        console.log();
+        break;
+
+      case 'error':
+        console.log(chalk.red('✗ Error:') + ` ${event.error.message}`);
+        break;
+
+      case 'done':
+        console.log(chalk.green('◀ Assistant:'));
+        const respLines = responseText.split('\n');
+        for (const line of respLines) {
+          console.log('  ' + line);
+        }
+        break;
+    }
+  }
+
+  console.log(chalk.dim('\n─'.repeat(50)));
+  console.log(chalk.green('✓') + ' Demo completed!\n');
+}
+
+main().catch((error) => {
+  console.error(chalk.red('Error:'), error.message);
+  process.exit(1);
+});

package/examples/basic.ts

@@ -0,0 +1,166 @@
+/**
+ * Basic example demonstrating multi-LLM support
+ *
+ * Run with: npx tsx examples/basic.ts
+ *
+ * Create a .env file with your API keys (see .env.example)
+ */
+
+import 'dotenv/config';
+
+// Setup proxy if configured
+const proxyUrl = process.env.HTTPS_PROXY || process.env.HTTP_PROXY;
+if (proxyUrl) {
+  const { setGlobalDispatcher, ProxyAgent } = await import('undici');
+  setGlobalDispatcher(new ProxyAgent(proxyUrl));
+  console.log(`Using proxy: ${proxyUrl}\n`);
+}
+
+import {
+  OpenAIProvider,
+  AnthropicProvider,
+  GeminiProvider,
+  createProvider,
+  inferProvider,
+  type LLMProvider,
+  type Message,
+  type ToolDefinition,
+} from '../src/index.js';
+
+// Simple tool definition for testing
+const tools: ToolDefinition[] = [
+  {
+    name: 'get_weather',
+    description: 'Get the current weather for a location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: {
+          type: 'string',
+          description: 'The city and state, e.g., San Francisco, CA',
+        },
+        unit: {
+          type: 'string',
+          enum: ['celsius', 'fahrenheit'],
+          description: 'Temperature unit',
+        },
+      },
+      required: ['location'],
+    },
+  },
+];
+
+async function testProvider(provider: LLMProvider, model: string) {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Testing ${provider.name} with model: ${model}`);
+  console.log('='.repeat(60));
+
+  const messages: Message[] = [{ role: 'user', content: 'What is the weather in Tokyo?' }];
+
+  try {
+    // Test non-streaming completion
+    console.log('\n--- Non-streaming completion ---');
+    const response = await provider.complete({
+      model,
+      messages,
+      tools,
+      systemPrompt: 'You are a helpful assistant. Use tools when appropriate.',
+      maxTokens: 1024,
+    });
+
+    console.log('Stop reason:', response.stopReason);
+    console.log('Content:');
+    for (const content of response.content) {
+      if (content.type === 'text') {
+        console.log(`  [text] ${content.text}`);
+      } else if (content.type === 'tool_use') {
+        console.log(`  [tool_use] ${content.name}(${JSON.stringify(content.input)})`);
+      }
+    }
+    if (response.usage) {
+      console.log(`Usage: ${response.usage.inputTokens} input, ${response.usage.outputTokens} output`);
+    }
+
+    // Test streaming completion
+    console.log('\n--- Streaming completion ---');
+    process.stdout.write('Response: ');
+    for await (const chunk of provider.stream({
+      model,
+      messages: [{ role: 'user', content: 'Say "hello world" in Japanese.' }],
+      maxTokens: 100,
+    })) {
+      if (chunk.type === 'text') {
+        process.stdout.write(chunk.text);
+      } else if (chunk.type === 'tool_start') {
+        process.stdout.write(`\n[Tool: ${chunk.name}]`);
+      } else if (chunk.type === 'done') {
+        console.log(`\n(Stop: ${chunk.response.stopReason})`);
+      }
+    }
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : error}`);
+  }
+}
+
+async function main() {
+  console.log('Recode - Multi-LLM Agent SDK Demo\n');
+
+  // Test each provider if API key is available
+  const tests: Array<{ provider: LLMProvider; model: string; envKey: string }> = [];
+
+  if (process.env.OPENAI_API_KEY) {
+    tests.push({
+      provider: new OpenAIProvider(),
+      model: 'gpt-4o-mini',
+      envKey: 'OPENAI_API_KEY',
+    });
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    tests.push({
+      provider: new AnthropicProvider(),
+      model: 'claude-3-5-sonnet-20241022',
+      envKey: 'ANTHROPIC_API_KEY',
+    });
+  }
+
+  if (process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY) {
+    tests.push({
+      provider: new GeminiProvider(),
+      model: 'gemini-2.0-flash',
+      envKey: 'GOOGLE_API_KEY',
+    });
+  }
+
+  if (tests.length === 0) {
+    console.log('No API keys found. Please set at least one of:');
+    console.log('  - OPENAI_API_KEY');
+    console.log('  - ANTHROPIC_API_KEY');
+    console.log('  - GOOGLE_API_KEY (or GEMINI_API_KEY)');
+    process.exit(1);
+  }
+
+  console.log(`Found ${tests.length} provider(s) with API keys.\n`);
+
+  // Test provider inference
+  console.log('--- Provider Inference Test ---');
+  console.log(`gpt-4o -> ${inferProvider('gpt-4o')}`);
+  console.log(`claude-3-opus -> ${inferProvider('claude-3-opus')}`);
+  console.log(`gemini-1.5-pro -> ${inferProvider('gemini-1.5-pro')}`);
+
+  // Test createProvider factory (use first available provider)
+  console.log('\n--- Factory Test ---');
+  const firstProvider = tests[0];
+  const providerName = firstProvider.provider.name as 'openai' | 'anthropic' | 'gemini';
+  const factoryProvider = createProvider({ provider: providerName });
+  console.log(`Created provider via factory: ${factoryProvider.name}`);
+
+  // Run provider tests
+  for (const test of tests) {
+    await testProvider(test.provider, test.model);
+  }
+
+  console.log('\n\nAll tests completed!');
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "gencode-ai",
+  "version": "0.1.0",
+  "description": "GenCode - An open-source, provider-agnostic AI coding assistant",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "gencode": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "npx tsx src/cli/index.tsx",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "example": "npx tsx examples/basic.ts"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "openai",
+    "anthropic",
+    "gemini",
+    "ai"
+  ],
+  "author": "Meng Yan",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@google/generative-ai": "^0.24.1",
+    "chalk": "^5.6.2",
+    "dotenv": "^17.2.3",
+    "fast-glob": "^3.3.3",
+    "glob": "^13.0.0",
+    "ink": "^6.6.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "openai": "^6.16.0",
+    "ora": "^9.0.0",
+    "react": "^19.2.3",
+    "undici": "^7.18.2",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@types/react": "^19.2.8",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}