god-code 0.4.1__tar.gz → 0.5.0__tar.gz

god_code-0.5.0/AGENTS.md

@@ -0,0 +1,215 @@
+# AGENTS.md — God Code Development Guide
+
+> 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** — a Python CLI agent that understands GDScript, .tscn scenes, collision layers, and Godot architecture patterns. It calls LLM APIs with Godot-specific tools and enforces 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.12+
+- **CLI**: click
+- **HTTP**: httpx (async)
+- **Models**: pydantic v2 (tool schemas, config)
+- **Image**: Pillow (screenshot encoding)
+- **Test**: pytest + pytest-asyncio
+- **Build**: hatchling
+- **CI**: GitHub Actions (auto-publish to PyPI on tag)
+
+## Current Version: 0.1.0
+
+**Completed**: CLI (ask/chat/info/setup/login/logout/status), 10 tools, LLM client with OpenAI-compatible API, Godot Playbook knowledge system (17 sections), .tscn parser/writer/validator, GDScript linter, collision planner, dependency graph, pattern advisor, consistency checker, error loop, context manager, first-run setup wizard, PyPI published.
+
+**157 tests**, ~4,000 lines production code.
+
+## Architecture
+
+```
+godot_agent/
+├── cli.py                        # Click CLI entry point + setup wizard
+├── runtime/
+│   ├── engine.py                 # Conversation loop (tool calling + context compaction + error loop)
+│   ├── config.py                 # AgentConfig (pydantic) + load from file/env
+│   ├── session.py                # Session persistence (.agent_sessions/*.json)
+│   ├── oauth.py                  # Codex refresh token flow
+│   ├── error_loop.py             # Godot output parsing + fix suggestions
+│   ├── context_manager.py        # Message compaction + file relevance scoring
+│   └── auth.py                   # AuthContext dataclass
+├── llm/
+│   ├── client.py                 # LLMClient (OpenAI-compatible, retry, content filter handling)
+│   ├── streaming.py              # SSE streaming
+│   └── vision.py                 # Image → base64 encoding
+├── tools/                        # 10 function-calling tools
+│   ├── base.py                   # BaseTool ABC + ToolResult
+│   ├── registry.py               # ToolRegistry (register, execute, to_openai_tools)
+│   ├── file_ops.py               # read_file, write_file, edit_file (path-contained)
+│   ├── search.py                 # grep, glob
+│   ├── list_dir.py               # list_dir
+│   ├── git.py                    # git (shlex-parsed)
+│   ├── shell.py                  # run_shell (blocked patterns)
+│   ├── godot_cli.py              # run_godot (GUT, validate, output parser)
+│   └── screenshot.py             # screenshot_scene (headless)
+├── godot/                        # Godot-specific analysis
+│   ├── project.py                # project.godot parser → GodotProject
+│   ├── scene_parser.py           # .tscn → TscnScene (nodes, resources, connections)
+│   ├── scene_writer.py           # add_node, set_property, remove_node, add_connection
+│   ├── tscn_validator.py         # Format validation + auto-fix ordering
+│   ├── gdscript_linter.py        # Naming, ordering, type annotations, anti-patterns
+│   ├── collision_planner.py      # Standard 8-layer scheme
+│   ├── consistency_checker.py    # Cross-file collision/signal/resource/group checks
+│   ├── dependency_graph.py       # Project-wide scene→script→resource graph
+│   ├── pattern_advisor.py        # Object pool, component, state machine suggestions
+│   └── resource_validator.py     # res:// path existence check
+└── prompts/
+    ├── system.py                 # Builds system prompt (identity + knowledge + discipline + context)
+    ├── godot_playbook.py         # 17 indexed knowledge sections
+    ├── knowledge_selector.py     # Context-aware section scoring + injection
+    └── build_discipline.py       # Incremental build-and-verify rules
+```
+
+## Key Patterns
+
+### Tool System
+Every tool inherits `BaseTool` with pydantic `Input`/`Output` models. The registry auto-generates OpenAI function calling schemas.
+
+```python
+class MyTool(BaseTool):
+    name = "my_tool"
+    description = "Does something"
+    class Input(BaseModel):
+        param: str = Field(description="...")
+    class Output(BaseModel):
+        result: str
+    async def execute(self, input: Input) -> ToolResult:
+        return ToolResult(output=self.Output(result="done"))
+```
+
+Register in `cli.py:build_registry()`.
+
+### Path Containment
+`file_ops.py` has a module-level `_project_root` set by CLI on startup. All read/write/edit operations validate paths are within project root. `set_project_root()` is called in `build_engine()`.
+
+### Engine Flow
+```
+user message → _maybe_compact() → client.chat() → tool_calls?
+  → yes: execute tools → _post_tool_validate() → loop
+  → no: return content
+```
+- Compaction triggers at ~80K estimated tokens
+- Post-tool validation runs `godot --headless --quit` after write_file/edit_file
+- Max tool rounds default: 20
+
+### Knowledge Injection
+`knowledge_selector.py` scores Playbook sections by keyword overlap with user prompt + file extensions. Top 4 sections injected (~2K tokens instead of full ~15K).
+
+### Error Loop Integration
+After any file-mutating tool call, engine runs Godot headless validation. If errors found, injects a system message telling the LLM to fix them before proceeding.
+
+## Development Rules
+
+### CRITICAL: Read Before Modify
+Never modify files without reading them first. This applies to both god-code source AND Godot project files the agent operates on.
+
+### Adding a New Tool
+1. Create `godot_agent/tools/your_tool.py` inheriting `BaseTool`
+2. Define `Input` and `Output` as pydantic `BaseModel`
+3. Implement `async execute()`
+4. Register in `cli.py:build_registry()`
+5. Add tests in `tests/tools/test_your_tool.py`
+6. Update README tool list
+
+### Adding Godot Knowledge
+Edit `godot_agent/prompts/godot_playbook.py`:
+- Each section: `(title, [keywords], content_string)`
+- Keywords drive auto-selection in `knowledge_selector.py`
+- Keep sections concise (~200 tokens each)
+
+### Adding Godot Analysis
+New analyzers go in `godot_agent/godot/`. Follow existing patterns:
+- Pure functions, no side effects
+- Return structured dataclasses
+- Include `format_*()` for LLM-readable output
+
+### Config
+`~/.config/god-code/config.json` with `GODOT_AGENT_*` env overrides:
+
+| Field | Default | Env Var |
+|-------|---------|---------|
+| api_key | "" | GODOT_AGENT_API_KEY |
+| base_url | https://api.openai.com/v1 | GODOT_AGENT_BASE_URL |
+| model | gpt-5.4 | GODOT_AGENT_MODEL |
+| godot_path | godot | GODOT_AGENT_GODOT_PATH |
+| oauth_token | null | GODOT_AGENT_OAUTH_TOKEN |
+
+OAuth client_id configurable via `GODOT_AGENT_OAUTH_CLIENT_ID`.
+
+## Testing
+
+```bash
+# Full suite (157 tests)
+python -m pytest tests/ -v
+
+# Specific module
+python -m pytest tests/godot/test_tscn_validator.py -v
+
+# E2E with mocked LLM
+python -m pytest tests/test_e2e.py -v
+```
+
+All tests use `tmp_path` fixture for isolation. LLM tests mock `httpx` responses. No real API calls in tests.
+
+## Release Process
+
+Automated via GitHub Actions:
+
+```bash
+# 1. Bump version in pyproject.toml
+# 2. Commit + tag
+git commit -am "release: v0.2.0"
+git tag v0.2.0
+git push && git push --tags
+# → GitHub Actions runs tests → publishes to PyPI
+```
+
+Requires `PYPI_API_TOKEN` in GitHub repo secrets.
+
+## Security Model
+
+- **File ops**: Restricted to project root (symlink-aware)
+- **Shell**: Blocked patterns (rm -rf /, sudo, curl|sh, etc.)
+- **Git**: shlex.split() for proper argument parsing
+- **API keys**: Stored with 600 permissions, masked in CLI output
+- **Content filter**: 400 errors retried, graceful fallback message
+
+## Roadmap
+
+### Phase 2: Editor Plugin Bridge
+- Godot EditorPlugin with WebSocket server
+- `editor_bridge.py` Python WebSocket client
+- Tier 1 operations: scene tree, properties, signals, run/stop game
+- Live viewport screenshots from editor
+
+### Phase 3: Hosted API
+- Cloudflare Worker proxy with Google OAuth
+- Free tier (50 req/day, gpt-4o-mini)
+- Pro tier ($12/mo, gpt-5.4 + vision)
+- Small model routing for simple tasks
+- Prompt caching for session continuity
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Package metadata, version, dependencies |
+| `CHANGELOG.md` | Version history |
+| `README.md` | User-facing documentation |
+| `CONTRIBUTING.md` | Contributor guide |
+| `.github/workflows/publish.yml` | Auto-publish to PyPI on tag |
+| `godot_agent/cli.py` | CLI commands + setup wizard |
+| `godot_agent/runtime/engine.py` | Core conversation loop |
+| `godot_agent/prompts/godot_playbook.py` | Godot knowledge base |

{god_code-0.4.1 → god_code-0.5.0}/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.4.1 → god_code-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: god-code
-Version: 0.4.1
+Version: 0.5.0
 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.1 → god_code-0.5.0}/README.md

@@ -5,6 +5,9 @@ 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
+- **Workspace-style chat TUI**: session snapshot, recent activity timeline, live tool feedback, and validation visibility
+- **Interaction modes**: `apply`, `plan`, `explain`, `review`, and `fix` with mode-aware prompts and tool access
+- **Session recovery**: autosave, `/sessions`, `/resume`, and 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
@@ -52,6 +55,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 +114,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 +130,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.0/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.0/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.0/godot_agent/agents/dispatcher.py

@@ -0,0 +1,152 @@
+"""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.allowed_tools = 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.0/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