- The active product now includes both the backend runtime and the first project-scoped TUI.
- Authoritative code lives under
deep_coder/plus the checked-in launcher scriptdeepcode. agentLoop.pyis still a legacy prototype and reference file. It is not the main entrypoint and it is not the authoritative implementation.- When behavior in
agentLoop.pyanddeep_coder/differ, followdeep_coder/.
The current shipped flow is:
- User
cds into a workspace. - User launches
deepcode. deep_coder/cli.pyresolves the current directory into a project record.- Runtime state is rooted under
~/.deepcode/projects/<project-key>/. - The Textual app renders one timeline plus a bottom composer/status strip.
- Submitting from the composer runs the harness and streams live events into the timeline.
- Session replay and session switching are limited to the active project.
The product is no longer just a backend runtime. It is now a terminal application built on top of that runtime.
The project is a package-based single-agent coding runtime with a TUI layer on top of clear module boundaries:
deep_coder/cli.py- Launch bootstrap.
- Resolves
pwdinto a project and starts the TUI.
deepcode- Checked-in launcher script.
deep_coder/main.py- Composition root.
- Builds config, model, tools, prompt, context manager, and harness.
deep_coder/projects/- Project registry and workspace identity.
- Maps a workspace path to a persistent
project_keyandstate_dir.
deep_coder/tui/- Textual application, timeline rendering, and modal screens.
- Owns composer submission, replay, and live event display.
deep_coder/harness/- Runtime orchestration.
- Opens sessions, prepares messages, calls the model, runs tools, records chat history, and emits timeline events.
deep_coder/models/- Model adapters.
- Current provider is DeepSeek through the OpenAI-compatible Python SDK.
deep_coder/tools/- Tool contracts plus builtin local coding tools.
- Current builtin tools:
bash,read_file,write_file,edit_file.
deep_coder/prompts/- System prompt rendering.
deep_coder/context/- Session persistence and message assembly.
- Includes a stable
ContextManager, a filesystem session store, and a simple append-only history strategy.
The intended current flow is:
- Resolve the active workspace and register or reopen it through
ProjectRegistry. - Build runtime from
deep_coder.main.build_runtime(project=...). - Start
DeepCodeApp. - Open or create a project-scoped session through the context layer.
- Render the active system prompt.
- Assemble request messages from session history plus current user input.
- Call the model adapter.
- Execute returned tool calls through the tool registry.
- Record assistant/tool chat messages into session history.
- Emit structured timeline events for replay and live TUI updates.
- Flush the session to storage.
- Stop when the model returns a final assistant answer.
Harnessis the orchestrator and should stay thin.Modelonly handles provider communication and normalized responses.Toolsexpose machine-readable schemas and local execution entrypoints.Promptmodules render the active system prompt without owning runtime orchestration.Contextowns session persistence and message history assembly.Projectsown workspace identity and project-scoped state roots.TUIowns presentation, replay, session switching, and user interaction wiring, not backend policy.- Extension points should be added by implementing concrete classes behind the existing base contracts, not by collapsing boundaries back into one file.
- Machine-readable metadata belongs in methods like
schema()andmanifest(), not in comments.
What exists now:
- single-agent runtime
- DeepSeek model adapter
- OpenAI-compatible SDK integration
- local coding tools
- project registry under
~/.deepcode/config.toml - project-scoped session storage
- persisted chat history and persisted timeline events
- Textual TUI with:
- top timeline
- bottom composer/status strip
- modal session switcher
- live harness event streaming
- session replay
- checked-in
deepcodelauncher
What is intentionally still thin or out of scope:
- no packaged install flow or console-script entrypoint beyond
deepcode - no global mixed-project session browser
- no advanced timeline folding, pagination, or virtualization
- no advanced context compaction yet
- no retry/backoff policy yet in the DeepSeek adapter
- no package-level subagent orchestration
- no background job manager
- no task graph runtime
Some of those ideas appear in agentLoop.py, but they are prototype ideas, not current product behavior.
- The runtime expects
DEEPSEEK_API_KEYin the environment. - Default runtime state lives under
~/.deepcode/. - The project registry lives at:
~/.deepcode/config.toml
- Project-scoped state lives at:
~/.deepcode/projects/<project-key>/
- Session storage currently uses:
sessions/<session-id>/meta.jsonsessions/<session-id>/messages.jsonlsessions/<session-id>/events.jsonlsessions/<session-id>/context/<strategy-name>/state.json
- Do not treat
agentLoop.pyas the main entrypoint. - Prefer changes inside
deep_coder/anddeepcodeunless the task is explicitly about the prototype. - Preserve the existing package boundaries when adding features.
- Add new tools, providers, prompts, stores, strategies, screens, or registry behavior as modular implementations instead of folding logic into the app shell.
- Keep file and command access workspace-bounded unless a task explicitly requires broader access.
- Keep runtime state out of the repository; use
~/.deepcode/or explicit overrides. - When changing TUI behavior, make sure replay and live event paths stay aligned.
When doing branch-based development:
- Do not work directly from the repository root working tree.
- Create dedicated worktrees under
.worktrees/at the repository root. - Use concise task-oriented branch names such as
feat/...orfix/.... - Remove worktrees after merge.
Commands:
git worktree add -b <branch-name> .worktrees/<branch-name> HEAD
cd .worktrees/<branch-name>
git worktree remove .worktrees/<branch-name>
git branch -d <branch-name>- Use the project venv, not the system Python:
source /home/wys/deep-code/.venv/bin/activate- or call
/home/wys/deep-code/.venv/bin/pythonand/home/wys/deep-code/.venv/bin/pytestdirectly
- In this repository, plain
pytestonPATHmay resolve to system Python and misstextual. - Preferred verification commands:
python3 -m pytest -q/home/wys/deep-code/.venv/bin/pytest -q
- Run the full suite after meaningful runtime or TUI changes.
- Start by reading:
deep_coder/cli.pydeep_coder/tui/app.pydeep_coder/main.pydeep_coder/harness/deepcoder/harness.pydeep_coder/projects/registry.pyarch/arch.md
- Use
agentLoop.pyonly as a roadmap for future capabilities or historical context. - If you need to add a feature that exists in the prototype but not in the package runtime, implement it as a modular
deep_coder/feature instead of copying prototype structure forward. - For branch history and implementation context, read:
docs/history/2026-03-25-deep-coder-backend-runtime-history.mddocs/history/2026-03-26-harness-backend-tui-history.md