feat(agents): per-project folder under ~/codec-projects/<slug>/ (Claude Code-style)#28
Merged
feat(agents): per-project folder under ~/codec-projects/<slug>/ (Claude Code-style)#28
Conversation
…de Code-style)
User feedback: when CODEC starts a project (Project mode), it should
create a real folder on the computer that can be opened in any IDE —
just like Claude Code does. Files the agent creates need to land
somewhere humans can browse to, not opaque ~/.codec/agents/<id>/artifacts/.
## What changes
- New helpers in `codec_agent_plan.py`:
- `_slugify(title)` → "build-a-telegram-bot" from "Build a Telegram bot"
- `create_project_folder(title, agent_id)` → creates
`~/codec-projects/<slug>/`, disambiguates collisions (-2, -3, ...)
- `_project_root()` reads `~/.codec/config.json:agents.project_root_dir`
override; defaults to `~/codec-projects/`. Env var override:
`CODEC_PROJECT_ROOT_DIR`.
- `create_agent()` calls `create_project_folder()` upfront, stores path
as `manifest.project_dir`. Folder exists by the time the user sees
the plan in the UI.
- `draft_plan()` + `draft_plan_with_clarification()` accept new
`project_dir` parameter. When provided, the Qwen prompt instructs
the LLM to default `permission_manifest.write_paths` to
`<project_dir>/**` so files land in the human-browseable folder.
- `POST /api/agents` response now includes `project_dir`.
- PWA chat (`codec_chat.html`) Project-mode response shows a styled
callout with the folder path + "open this folder in your IDE" hint.
## Tests
8 new tests in `tests/test_agent_plan.py`:
- `test_slugify_basic` — common cases
- `test_slugify_handles_unicode_and_empty` — unicode strip + empty fallback
- `test_slugify_truncates_long_titles` — `MAX_PROJECT_SLUG_LEN=50` enforced
- `test_create_project_folder_creates_dir` — happy path
- `test_create_project_folder_disambiguates_collisions` — -2 / -3 suffix
- `test_create_agent_writes_project_dir_in_manifest` — end-to-end
- `test_draft_plan_includes_project_dir_in_qwen_prompt` — prompt contains path
- `test_project_root_config_override` — config.json wins over default
`temp_codec_dir` fixture extended to also redirect `_PROJECT_ROOT` to
tmp_path so tests don't touch real `~/codec-projects/`.
## Test counts
- `test_agent_plan.py`: 31 → 39 (+8)
- Full suite: 930 → 938, same 20/73 baseline
## Compat
- `manifest.project_dir` is a NEW field. Old agents (pre-Phase-3.5) won't
have it; consumers must `manifest.get("project_dir")` not subscript.
- Plan schema unchanged (still `schema:1`). Project_dir lives in manifest,
not plan, so plan_hash tamper detection is unaffected.
After merge + deploy, dropping a project via `/chat` Project mode creates
e.g. `~/codec-projects/marbella-property-bot/` and the agent's plan
defaults `write_paths` to `~/codec-projects/marbella-property-bot/**`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per user feedback (paraphrased): "when CODEC starts a project, it should create a new folder on the computer, just like Claude Code". Currently agents only have
~/.codec/agents/<id>/artifacts/— opaque, can't be opened in an IDE.This PR adds a real, human-browseable project folder under
~/codec-projects/<slug>/, created at agent spawn time. The plan-drafter Qwen prompt is told to defaultpermission_manifest.write_pathsto that folder, so files the agent creates land where the user can open them.Why this is a Step 12 prerequisite
Without a real folder, the anchor example (Marbella property bot) has no actual home — the bot files would live in an opaque
~/.codec/agents/<id>/artifacts/directory. Real project folder ships first; then the anchor example flows through it.What changes
codec_agent_plan.py_slugify,_project_root,create_project_folder.create_agentcalls it.draft_planacceptsproject_dir. New constant_PROJECT_ROOT=~/codec-projects/. New env varCODEC_PROJECT_ROOT_DIR. New config knob~/.codec/config.json:agents.project_root_dir.routes/agents.pyPOST /api/agentsresponse includesproject_dir.codec_chat.htmltests/test_agent_plan.pytemp_codec_dirfixture redirects_PROJECT_ROOTto tmp.Slug examples
~/codec-projects/build-a-telegram-bot-for-marbella-property/~/codec-projects/eur-usd-vol-monitor/…/eur-usd-vol-monitor/and…/eur-usd-vol-monitor-2/…/project/Test plan
tests/test_agent_plan.py— 31 → 39 (+8 new tests)cd ~/codec-repo && git pull && pm2 restart codec-dashboard codec-agent-runner/chatProject mode → verify~/codec-projects/<slug>/folder created → response shows folder path → opens cleanly in any IDEBackward compatibility
manifest.project_diris a NEW field. Old agents won't have it; consumers usemanifest.get("project_dir"), not subscript.schema:1).project_dirlives in manifest, NOT plan, soplan_hashtamper detection is unaffected.🤖 Generated with Claude Code