god-code 0.4.3__tar.gz → 0.5.1__tar.gz

god_code-0.4.3/CLAUDE.md → god_code-0.5.1/AGENTS.md

@@ -1,6 +1,6 @@
-# CLAUDE.md — God Code Development Guide
+# AGENTS.md — God Code Development Guide
 
-> AI coding agent specialized for Godot 4.4 game development. This file guides Claude Code when working on the god-code codebase itself.
+> AI coding agent specialized for Godot 4.4 game development. This file guides Codex when working on the god-code codebase itself.
 
 ## Project Identity
 

{god_code-0.4.3 → god_code-0.5.1}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to God Code will be documented in this file.
 
+## [Unreleased]
+
+### Added
+- Workspace-style chat TUI with session snapshot, recent activity, and live streaming panels
+- Interaction modes (`apply`, `plan`, `explain`, `review`, `fix`) with mode-aware tool availability
+- Autosaved session metadata with `/sessions`, `/resume`, `/new`, and project-aware restore flow
+
+### Changed
+- Unified `ask` and `chat` rendering pipeline, including tool progress and validation feedback
+- Improved post-tool validation visibility and tool result summaries in interactive sessions
+- Session persistence now preserves assistant tool calls and richer metadata for restore
+
 ## [0.1.0] - 2026-04-02
 
 ### Added

god_code-0.5.1/CLAUDE.md

@@ -0,0 +1,196 @@
+# CLAUDE.md — God Code Development Guide
+
+> AI coding agent specialized for Godot 4.4 game development. This file guides Claude Code when working on the god-code codebase itself.
+
+## Project Identity
+
+**god-code** — a Python CLI agent that understands GDScript, .tscn scenes, collision layers, and Godot architecture patterns. Multi-provider LLM support with 29 Godot-specific tools, AI sprite generation, and incremental build-and-verify discipline.
+
+**PyPI**: `pip install god-code`
+**GitHub**: https://github.com/888wing/god-code
+**License**: GPL-3.0
+
+## Tech Stack
+
+- **Language**: Python 3.9+ (uses `from __future__ import annotations` for 3.10+ syntax)
+- **CLI**: click
+- **HTTP**: httpx (async)
+- **Models**: pydantic v2 (tool schemas, config, structured outputs)
+- **Image**: Pillow (screenshot + sprite post-processing)
+- **TUI**: rich (panels, markdown, diff, tables, spinner) + prompt_toolkit (history, autocomplete)
+- **Test**: pytest + pytest-asyncio (383 tests)
+- **Build**: hatchling
+- **CI**: GitHub Actions (auto-publish to PyPI on tag)
+
+## Current Version: 0.5.1
+
+**Stats**: 70 source files, 55 test files, ~11K lines, 383 tests, 29 tools.
+
+## Architecture
+
+```
+godot_agent/
+├── cli.py                          # Click CLI + setup wizard + chat loop
+├── agents/                         # Multi-agent system
+│   ├── configs.py                  # Agent role configurations
+│   ├── dispatcher.py               # Planner/worker/reviewer dispatch
+│   └── results.py                  # Agent result types
+├── runtime/
+│   ├── engine.py                   # Conversation loop (tools, streaming, quality gates, review)
+│   ├── config.py                   # AgentConfig (pydantic) + env overrides
+│   ├── session.py                  # Session persistence with metadata
+│   ├── oauth.py                    # Codex refresh token flow
+│   ├── error_loop.py               # Godot output parsing + fix suggestions
+│   ├── context_manager.py          # Smart compression with working memory (1.05M context)
+│   ├── events.py                   # Engine event system for TUI
+│   ├── modes.py                    # Interaction modes (apply/plan/explain/review/fix)
+│   ├── providers.py                # Provider detection (openai/anthropic/gemini/xai/openrouter)
+│   ├── quality_gate.py             # Post-tool validation pipeline
+│   ├── reviewer.py                 # Automated code review
+│   ├── playtest_harness.py         # Automated gameplay testing
+│   ├── gameplay_reviewer.py        # Gameplay quality analysis
+│   ├── runtime_bridge.py           # Runtime state snapshots
+│   ├── design_memory.py            # Persistent design decisions
+│   └── auth.py                     # Auth context
+├── llm/
+│   ├── client.py                   # LLMClient with retry, content filter handling
+│   ├── types.py                    # Message, ToolCall, TokenUsage, ChatResponse, LLMConfig
+│   ├── streaming.py                # SSE streaming with tool call assembly
+│   ├── vision.py                   # Image encoding
+│   └── adapters/                   # Provider-specific adapters
+│       ├── base.py                 # Adapter interface
+│       ├── openai.py               # OpenAI/OpenRouter adapter
+│       └── anthropic.py            # Anthropic adapter
+├── tools/                          # 29 function-calling tools
+│   ├── base.py                     # BaseTool ABC (strict mode support)
+│   ├── registry.py                 # ToolRegistry with security pipeline
+│   ├── file_ops.py                 # read_file, write_file, edit_file (path-contained)
+│   ├── script_tools.py             # read_script, edit_script, lint_script
+│   ├── scene_tools.py              # read_scene, scene_tree, add/write/remove scene nodes
+│   ├── analysis_tools.py           # validate_project, check_consistency, dependency_graph, impact
+│   ├── search.py                   # grep, glob
+│   ├── list_dir.py                 # list_dir
+│   ├── git.py                      # git (shlex-parsed)
+│   ├── shell.py                    # run_shell (3 safety levels)
+│   ├── godot_cli.py                # run_godot (GUT, validate, output parser)
+│   ├── screenshot.py               # screenshot_scene (headless)
+│   ├── image_gen.py                # generate_sprite (AI pixel art + post-processing)
+│   ├── web_search.py               # web_search (Godot docs, web)
+│   ├── memory_tool.py              # design memory read/write
+│   └── editor_bridge.py            # runtime snapshot, playtest
+├── godot/                          # Godot-specific analysis
+│   ├── project.py                  # project.godot parser
+│   ├── scene_parser.py             # .tscn → TscnScene
+│   ├── scene_writer.py             # Structured .tscn modification
+│   ├── tscn_validator.py           # Format validation + auto-fix
+│   ├── gdscript_linter.py          # Style, naming, type annotations
+│   ├── collision_planner.py        # Standard 8-layer scheme
+│   ├── consistency_checker.py      # Cross-file checks
+│   ├── dependency_graph.py         # Project-wide file graph
+│   ├── pattern_advisor.py          # Design pattern suggestions
+│   ├── impact_analysis.py          # Change impact analysis
+│   └── resource_validator.py       # res:// path checks
+├── prompts/
+│   ├── system.py                   # Compatibility wrapper
+│   ├── assembler.py                # Full prompt assembly pipeline
+│   ├── godot_playbook.py           # 17 knowledge sections
+│   ├── knowledge_selector.py       # Context-aware section scoring
+│   ├── skill_library.py            # Skill definitions
+│   ├── skill_selector.py           # Dynamic skill activation
+│   ├── build_discipline.py         # Build-and-verify rules
+│   └── image_templates.py          # Pixel art prompt templates
+├── security/
+│   ├── classifier.py               # Tool risk classification
+│   ├── hooks.py                    # Pre/post execution hooks
+│   ├── policies.py                 # Execution context + policies
+│   ├── protected_paths.py          # Path protection rules
+│   └── tool_pipeline.py            # Tool execution pipeline
+├── testing/
+│   └── scenario_runner.py          # Automated test scenarios
+└── tui/
+    ├── display.py                  # Rich TUI components
+    └── input_handler.py            # prompt_toolkit input + autocomplete
+```
+
+## Key Patterns
+
+### Tool System
+Every tool inherits `BaseTool`. Supports `strict` mode for GPT-5+ structured outputs. Security pipeline validates path containment and safety level before execution.
+
+### Provider Adapters
+`llm/adapters/` handles provider-specific request/response formats:
+- OpenAI: `max_completion_tokens` for gpt-5+, `max_tokens` for others
+- Anthropic: `thinking` budget for reasoning models
+- Gemini: `reasoning_effort` parameter
+
+### Engine Loop Phases
+```
+PREPARE_CONTEXT → CALL_MODEL → EXECUTE_TOOLS → RUN_QUALITY_GATE → RUN_REVIEWER → NEXT_ROUND → DONE
+```
+
+### Context Management (1.05M window)
+Smart compression at 75% (787K tokens):
+1. Extract working memory (modified files, decisions, errors)
+2. Keep 20 recent messages intact
+3. Replace old turns with memory summary
+4. Tell LLM to re-read files if needed
+
+### Interaction Modes
+- `apply`: Full tool access, write code
+- `plan`: Read-only tools, design first
+- `explain`: Read-only, educational
+- `review`: Read-only, quality analysis
+- `fix`: Full tools, error-focused
+
+## Development Rules
+
+### Adding a New Tool
+1. Create in `godot_agent/tools/your_tool.py` inheriting `BaseTool`
+2. Define `Input`/`Output` as pydantic `BaseModel` (all fields must have defaults for strict mode)
+3. Implement `async execute()`, `is_read_only()`, `is_destructive()`
+4. Register in `cli.py:build_registry()`
+5. Add to `prompts/system.py` active_tools list
+6. Add tests in `tests/tools/`
+
+### Adding a Provider
+1. Create adapter in `godot_agent/llm/adapters/`
+2. Register in `runtime/providers.py`
+3. Add detection rules (model prefix, base_url pattern)
+
+## Config Reference
+
+`~/.config/god-code/config.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| api_key | "" | LLM API key |
+| provider | "openai" | openai, anthropic, gemini, xai, openrouter |
+| model | "gpt-5.4" | Model ID |
+| reasoning_effort | "high" | low, medium, high |
+| mode | "apply" | apply, plan, explain, review, fix |
+| language | "en" | en, zh-TW, ja, ko |
+| verbosity | "normal" | concise, normal, detailed |
+| auto_validate | true | Run Godot after file changes |
+| auto_commit | false | Suggest git commit |
+| token_budget | 0 | Max tokens (0=unlimited) |
+| safety | "normal" | strict, normal, permissive |
+| streaming | true | Stream responses |
+| extra_prompt | "" | Custom instructions |
+
+## Testing
+
+```bash
+python -m pytest tests/ -v          # Full suite (383 tests)
+python -m pytest tests/tools/ -v    # Tool tests only
+python -m pytest tests/e2e/ -v      # E2E integration tests
+```
+
+## Release
+
+```bash
+# Bump version in pyproject.toml + cli.py _VERSION
+git commit -am "release: v0.5.1"
+git tag v0.5.1
+git push && git push --tags
+# → GitHub Actions auto-publishes to PyPI
+```

{god_code-0.4.3 → god_code-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: god-code
-Version: 0.4.3
+Version: 0.5.1
 Summary: AI coding agent specialized for Godot game development
 Project-URL: Homepage, https://github.com/chuisiufai/god-code
 Project-URL: Repository, https://github.com/chuisiufai/god-code

{god_code-0.4.3 → god_code-0.5.1}/README.md

@@ -4,12 +4,20 @@ AI coding agent specialized for Godot 4.4 game development. Unlike generic codin
 
 ## Features
 
-- **10 tools**: read/write/edit files, grep/glob search, git, shell, Godot headless runner, screenshot capture
+- **29 tools**: file ops, scene manipulation, script editing, search, git, shell, Godot headless runner, screenshot, AI sprite generation, web search
+- **AI sprite generation**: pixel art pipeline with chroma key removal, auto-crop, nearest-neighbor resize, style presets
+- **Structured Outputs**: strict JSON schemas for gpt-5+ models — zero tool call parse errors
+- **Web search**: query Godot docs and web when built-in knowledge isn't enough
+- **Workspace-style chat TUI**: session snapshot, activity timeline, live tool feedback, streaming output
+- **Interaction modes**: `apply`, `plan`, `explain`, `review`, `fix` with mode-aware prompts and tool access
+- **Multi-provider**: OpenAI (gpt-5.4), Anthropic (claude-sonnet-4.6), Google (gemini), xAI (grok), OpenRouter, local models
+- **Session recovery**: autosave, `/sessions`, `/resume`, project-aware session metadata
 - **Godot-native understanding**: project.godot parser, .tscn scene parser/writer/validator, collision layer planner
-- **Code quality**: GDScript linter (naming, ordering, type annotations), cross-file consistency checker, design pattern advisor
-- **Smart knowledge injection**: 17 Godot Playbook sections auto-selected by task context
-- **Build discipline**: incremental build-and-verify rules enforced via system prompt
-- **Vision support**: send screenshots + reference images to multimodal LLMs
+- **Code quality**: GDScript linter, cross-file consistency checker, design pattern advisor, impact analysis
+- **Smart knowledge injection**: 17 Godot Playbook sections auto-selected by task context + skill system
+- **Build discipline**: incremental build-and-verify with quality gates and automated review
+- **Security**: path containment, shell command blocking (3 safety levels), tool execution pipeline
+- **1.05M context window**: smart compression with working memory extraction at 75% threshold
 
 ## Install
 
@@ -52,6 +60,9 @@ EOF
 # Single prompt
 god-code ask "Add a health bar to the player scene" --project ./my-game
 
+# Script-friendly plain output
+god-code ask "Summarize this project" --project ./my-game --plain
+
 # Interactive chat
 god-code chat --project ./my-game
 
@@ -108,9 +119,14 @@ god-code logout   # Removes stored credentials
   "base_url": "https://api.openai.com/v1",
   "model": "gpt-5.4",
   "oauth_token": null,
+  "mode": "apply",
   "max_turns": 20,
   "max_tokens": 4096,
   "temperature": 0.0,
+  "auto_validate": true,
+  "auto_commit": false,
+  "streaming": true,
+  "autosave_session": true,
   "screenshot_max_iterations": 5,
   "godot_path": "godot",
   "session_dir": ".agent_sessions"
@@ -119,6 +135,16 @@ god-code logout   # Removes stored credentials
 
 All fields can be overridden with `GODOT_AGENT_` prefixed environment variables.
 
+## Chat Commands
+
+Interactive chat supports:
+
+- `/mode [apply|plan|explain|review|fix]`
+- `/sessions` and `/resume [session-id]`
+- `/new` to start a fresh session
+- `/workspace` to re-render the session snapshot
+- `/set <key> <value>` for live configuration changes
+
 ## System Prompt & Output Quality
 
 God Code's system prompt is dynamically assembled from:

god_code-0.5.1/godot_agent/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Multi-agent orchestration primitives for God Code."""
+
+from godot_agent.agents.configs import AGENT_CONFIGS, AgentConfig
+from godot_agent.agents.dispatcher import AgentDispatcher
+from godot_agent.agents.results import AgentTaskResult
+
+__all__ = [
+    "AGENT_CONFIGS",
+    "AgentConfig",
+    "AgentDispatcher",
+    "AgentTaskResult",
+]

god_code-0.5.1/godot_agent/agents/configs.py

@@ -0,0 +1,80 @@
+"""Built-in role configurations for multi-agent orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from godot_agent.runtime.modes import allowed_tools_for_mode
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    name: str
+    mode: str
+    prompt: str
+    allowed_tools: set[str]
+    auto_validate: bool = False
+    max_tool_rounds: int = 8
+
+
+_READ_ONLY_TOOLS = allowed_tools_for_mode("plan")
+_WORKER_TOOLS = allowed_tools_for_mode("apply")
+
+
+AGENT_CONFIGS: dict[str, AgentConfig] = {
+    "planner": AgentConfig(
+        name="planner",
+        mode="plan",
+        prompt=(
+            "You are the Planner agent. Inspect the project and produce a concrete implementation plan, "
+            "risks, and validation strategy. Do not edit files."
+        ),
+        allowed_tools=set(_READ_ONLY_TOOLS),
+        auto_validate=False,
+        max_tool_rounds=6,
+    ),
+    "explorer": AgentConfig(
+        name="explorer",
+        mode="review",
+        prompt=(
+            "You are the Explorer agent. Read the project, map the relevant scripts/scenes/resources, "
+            "and return concise findings. Do not edit files."
+        ),
+        allowed_tools=set(_READ_ONLY_TOOLS),
+        auto_validate=False,
+        max_tool_rounds=6,
+    ),
+    "worker": AgentConfig(
+        name="worker",
+        mode="apply",
+        prompt=(
+            "You are the Worker agent. Implement the requested change with the smallest viable edit, "
+            "then rely on validation and reviewer feedback to converge."
+        ),
+        allowed_tools=set(_WORKER_TOOLS),
+        auto_validate=True,
+        max_tool_rounds=12,
+    ),
+    "reviewer": AgentConfig(
+        name="reviewer",
+        mode="review",
+        prompt=(
+            "You are the Reviewer agent. Validate the changes adversarially and report concrete findings. "
+            "Do not edit files."
+        ),
+        allowed_tools=set(_READ_ONLY_TOOLS),
+        auto_validate=False,
+        max_tool_rounds=4,
+    ),
+    "playtest_analyst": AgentConfig(
+        name="playtest_analyst",
+        mode="review",
+        prompt=(
+            "You are the Playtest Analyst agent. Evaluate runtime evidence and scenario-based playtest output, "
+            "then explain whether the gameplay intent still holds."
+        ),
+        allowed_tools=set(_READ_ONLY_TOOLS),
+        auto_validate=False,
+        max_tool_rounds=4,
+    ),
+}

god_code-0.5.1/godot_agent/agents/dispatcher.py

@@ -0,0 +1,153 @@
+"""Synchronous multi-agent dispatcher."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+from godot_agent.godot.impact_analysis import format_impact_report, infer_request_impact
+from godot_agent.agents.configs import AGENT_CONFIGS, AgentConfig
+from godot_agent.agents.results import AgentTaskResult
+from godot_agent.llm.client import LLMClient
+from godot_agent.prompts.assembler import PromptAssembler, PromptContext
+from godot_agent.runtime.engine import ConversationEngine
+from godot_agent.runtime.playtest_harness import format_playtest_report, run_playtest_harness
+from godot_agent.runtime.quality_gate import QualityGateReport
+from godot_agent.runtime.runtime_bridge import get_runtime_snapshot
+from godot_agent.runtime.reviewer import format_review_report, review_changes
+from godot_agent.tools.registry import ToolRegistry
+
+
+class AgentDispatcher:
+    """Creates role-scoped engines and deterministic review passes."""
+
+    def __init__(
+        self,
+        *,
+        client: LLMClient,
+        registry: ToolRegistry,
+        prompt_context: PromptContext | None,
+        project_path: str | None,
+        godot_path: str = "godot",
+        base_allowed_tools: set[str] | None = None,
+    ) -> None:
+        self.client = client
+        self.registry = registry
+        self.prompt_context = prompt_context
+        self.project_path = project_path
+        self.godot_path = godot_path
+        self.base_allowed_tools = set(base_allowed_tools) if base_allowed_tools is not None else None
+
+    def _clone_registry(self) -> ToolRegistry:
+        cloned = ToolRegistry()
+        for tool in self.registry.list_tools():
+            cloned.register(tool)
+        return cloned
+
+    def resolve_allowed_tools(self, role: str) -> set[str]:
+        config = AGENT_CONFIGS[role]
+        if self.base_allowed_tools is None:
+            return set(config.allowed_tools)
+        return set(config.allowed_tools & self.base_allowed_tools)
+
+    def _build_prompt_assembler(self, config: AgentConfig) -> PromptAssembler | None:
+        if self.prompt_context is None:
+            return None
+        context = replace(
+            self.prompt_context,
+            mode=config.mode,
+            extra_prompt="\n\n".join(
+                section for section in [self.prompt_context.extra_prompt, config.prompt] if section
+            ),
+        )
+        return PromptAssembler(context)
+
+    def _build_engine(self, config: AgentConfig, *, user_hint: str) -> ConversationEngine:
+        registry = self._clone_registry()
+        prompt_assembler = self._build_prompt_assembler(config)
+        allowed_tools = self.resolve_allowed_tools(config.name)
+        if prompt_assembler is not None:
+            system_prompt = prompt_assembler.build(
+                user_hint=user_hint,
+                active_tools=[tool.name for tool in registry.list_tools() if tool.name in allowed_tools],
+            )
+        else:
+            system_prompt = config.prompt
+
+        engine = ConversationEngine(
+            client=self.client,
+            registry=registry,
+            system_prompt=system_prompt,
+            max_tool_rounds=config.max_tool_rounds,
+            project_path=self.project_path,
+            godot_path=self.godot_path,
+            auto_validate=config.auto_validate,
+            prompt_assembler=prompt_assembler,
+            mode=config.mode,
+        )
+        engine.base_allowed_tools = set(allowed_tools)
+        engine.allowed_tools = set(allowed_tools)
+        return engine
+
+    async def run_planner(self, task: str) -> AgentTaskResult:
+        config = AGENT_CONFIGS["planner"]
+        engine = self._build_engine(config, user_hint=task)
+        planning_prompt = task
+        if self.project_path:
+            impact_report = infer_request_impact(Path(self.project_path), task)
+            planning_prompt = f"{task}\n\nLikely impact before implementation:\n{format_impact_report(impact_report)}"
+        content = await engine.submit(planning_prompt)
+        return AgentTaskResult(
+            role=config.name,
+            content=content,
+            used_tools=engine.last_turn.tools_called if engine.last_turn else [],
+        )
+
+    async def run_worker(self, task: str, *, plan: str = "") -> AgentTaskResult:
+        config = AGENT_CONFIGS["worker"]
+        prompt = task if not plan else f"{task}\n\nApproved plan:\n{plan}"
+        engine = self._build_engine(config, user_hint=task)
+        content = await engine.submit(prompt)
+        verdict = "FAIL" if engine.last_review_report and engine.last_review_report.requires_fix else "PASS"
+        return AgentTaskResult(
+            role=config.name,
+            content=content,
+            verdict=verdict,
+            used_tools=engine.last_turn.tools_called if engine.last_turn else [],
+        )
+
+    async def run_reviewer(
+        self,
+        *,
+        changed_files: set[str],
+        quality_report: QualityGateReport | None = None,
+    ) -> AgentTaskResult:
+        if not self.project_path:
+            return AgentTaskResult(role="reviewer", verdict="PASS", content="No project path configured.")
+        report = await review_changes(
+            project_root=Path(self.project_path),
+            changed_files=changed_files,
+            godot_path=self.godot_path,
+            quality_report=quality_report,
+        )
+        return AgentTaskResult(
+            role="reviewer",
+            content=format_review_report(report),
+            verdict=report.verdict,
+            raw=report,
+        )
+
+    async def run_playtest_analyst(self, *, changed_files: set[str]) -> AgentTaskResult:
+        if not self.project_path:
+            return AgentTaskResult(role="playtest_analyst", verdict="PASS", content="No project path configured.")
+        report = run_playtest_harness(
+            project_root=Path(self.project_path),
+            changed_files=changed_files,
+            runtime_snapshot=get_runtime_snapshot(),
+        )
+        return AgentTaskResult(
+            role="playtest_analyst",
+            content=format_playtest_report(report),
+            verdict=report.verdict,
+            raw=report,
+        )

god_code-0.5.1/godot_agent/agents/results.py

@@ -0,0 +1,15 @@
+"""Structured results for sub-agent execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AgentTaskResult:
+    role: str
+    content: str = ""
+    verdict: str = "PASS"
+    notes: list[str] = field(default_factory=list)
+    used_tools: list[str] = field(default_factory=list)
+    raw: object | None = None