sfcode: Instructions file for Codex

sfcode

CLI coding agent in the spirit of Claude Code, written in PHP with Symfony AI and the Symfony TUI component.

Stack

• PHP 8.4.1+, ext-ctype / curl / iconv / json / mbstring
• Symfony 8.1 (Console, DependencyInjection, Tui, Runtime)
• Symfony AI Platform + Agent (Toolbox, #[AsTool])
• amphp/http-client for true async HTTP streaming
• Composer 2.x

Running the project

composer install
cp .env.example .env.local && $EDITOR .env.local   # paste OPENAI_API_KEY
php bin/sfcode

Code conventions

• PSR-12, declare(strict_types=1); everywhere.
• Standard Symfony 8.1 DI kernel (AbstractKernel + KernelTrait + ConsoleBundle).
• One tool = one final class with __invoke() and #[AsTool('name', 'description')].
• No obvious comments — only the non-trivial why gets a comment.
• All code, comments and user-facing strings are in English (the assistant's reply language follows the user's prompt language).
• Custom exceptions extend Sfcode\Exception\ExceptionInterface.

Quality gates

composer qa     # php-cs-fixer dry-run + phpstan level 8
composer cs-fix # apply style fixes

Entry points

• bin/sfcode → Sfcode\Command\ChatCommand (default command)
• Agentic loop core: Sfcode\Agent\AgentLoop::turn() / turnStream()
• Tools: src/Tool/*.php (one file = one tool)
• Permissions: src/Permission/PermissionManager.php
• Skills: src/Skill/SkillLoader.php (project > user cascade, Claude Code compatible)
• TUI choreography: src/Tui/TurnRunner.php

Out of scope (by design)

MCP, subagents, hooks, OS sandbox, advanced context compaction, cross-session memory. These are explicitly out of the current scope but documented as future work in CHANGELOG.md.