Skip to content

chatgpt-coding-workflow.md

Latest commit

 

History

History
205 lines (144 loc) · 6.1 KB

chatgpt-coding-workflow.md

File metadata and controls

205 lines (144 loc) · 6.1 KB
Raw

ChatGPT Coding Workflow

DevSpace brings a Codex-style coding-agent loop to ChatGPT and other MCP hosts: inspect the repo, follow local instructions, make scoped edits, run verification, and show the user what changed.

Open One Workspace

ChatGPT should call open_workspace once for a project folder:

{
  "path": "~/work/my-project"
}

The result includes a workspaceId. All later file, search, edit, show-changes, and shell calls should reuse that same workspaceId.

Do not reopen the same folder unless:

  • the workspaceId is rejected as unknown
  • the user switches to another folder
  • the user switches between checkout and worktree mode
  • the user explicitly asks to reopen

Checkout Mode

Checkout mode is the default. DevSpace opens the actual directory:

{
  "path": "~/work/my-project"
}

Use this when the user wants ChatGPT to work in the current checkout.

Worktree Mode

Use worktree mode for isolated parallel work:

{
  "path": "~/work/my-project",
  "mode": "worktree"
}

Managed worktrees are created under:

~/.devspace/worktrees

Worktree mode requires a Git repository with at least one commit. It starts from HEAD unless baseRef is provided.

Uncommitted source checkout changes are not copied into the managed worktree. DevSpace reports when the source checkout was dirty so the model can decide how to proceed with the user.

Project Instructions

When a workspace opens, DevSpace loads root-level instruction files:

  • AGENTS.md
  • AGENTS.MD
  • CLAUDE.md
  • CLAUDE.MD

Nested instruction files are returned as availableAgentsFiles. The model should read the relevant nested file before working under that directory.

This keeps instructions explicit and inspectable instead of silently injecting new context during later tool calls.

Skills

Skills are enabled by default for coding-agent workflows.

DevSpace discovers standard Agent Skills from:

  • ~/.agents/skills
  • project .agents/skills

It also keeps compatibility with:

  • DEVSPACE_AGENT_DIR/skills, defaulting to ~/.codex/skills
  • additional paths from DEVSPACE_SKILL_PATHS

Legacy project paths such as .pi/skills can be added through DEVSPACE_SKILL_PATHS when needed.

When open_workspace returns matching skills, the model should read the advertised SKILL.md before following that skill.

Skill paths may be outside the workspace. DevSpace only permits reading:

  • advertised SKILL.md files
  • files under a skill directory after that skill's SKILL.md has been read

Set DEVSPACE_SKILLS=0 to hide skills from workspace output.

Goal Tracking

Goal tracking is optional and disabled by default. Start DevSpace with:

DEVSPACE_GOALS=1 devspace serve

When enabled, DevSpace exposes workspace-scoped goal tools:

  • get_goal
  • set_goal
  • update_goal
  • clear_goal

A goal belongs to the opened workspaceId. It is durable DevSpace state that helps the model recover the full objective, progress summary, and next step after compaction, summary messages, long gaps, or lost context. The model should call get_goal in those moments and before declaring a multi-step goal complete.

This is not autonomous Codex goal mode, and it is not intended to claim one-for-one feature parity with Codex goals. DevSpace is an MCP server, so it can provide durable goal state and model-visible tools, but it cannot currently control the host model lifecycle.

Current gaps and open questions:

  • DevSpace cannot wake the model for automatic continuation turns when a thread becomes idle.
  • DevSpace cannot inject hidden goal context into every model turn the way a harness can.
  • DevSpace cannot directly detect that the host compacted the conversation; the model has to call get_goal after seeing a summary, losing context, or resuming work.
  • DevSpace does not receive reliable model token usage, so goal token budgets are intentionally not implemented.
  • DevSpace scopes goals to workspaceId, not to the host's chat thread, because MCP does not expose a stable ChatGPT or Claude thread identifier.
  • Future work may explore host-provided session/thread metadata, explicit UI controls for goals, richer progress history, and better recovery hooks if MCP hosts expose lifecycle events.

Tool Names

DevSpace exposes these tool names:

  • open_workspace
  • read
  • write
  • edit
  • bash

When DEVSPACE_GOALS=1, DevSpace also exposes get_goal, set_goal, update_goal, and clear_goal across tool modes.

By default, DevSpace also runs in DEVSPACE_TOOL_MODE=minimal, so dedicated grep, glob, and ls tools are hidden. Use bash with command-line tools such as rg, find, and ls for search and directory inspection.

Use DEVSPACE_TOOL_MODE=full to restore dedicated search and directory tools.

The experimental Codex-style surface is enabled with DEVSPACE_TOOL_MODE=codex. It exposes:

  • open_workspace
  • read
  • apply_patch
  • exec_command
  • write_stdin

In this mode, write, edit, bash, grep, glob, and ls are not registered. exec_command returns a process session ID when a command is still running after its yield window. Use write_stdin to poll it, send input, resize a PTY, or send Ctrl-C. Set tty: true only for commands that need a terminal.

Show Changes

By default, DEVSPACE_WIDGETS=full.

In that mode, DevSpace attaches widget UI to the exposed workspace, file, edit, and shell tools. The aggregate show_changes tool is not exposed by default.

Use DEVSPACE_WIDGETS=off to disable widget UI, or DEVSPACE_WIDGETS=changes to expose the aggregate show-changes flow.

When show_changes is exposed, models should call it exactly once after the final file modification in any turn that changes files. The tool only requires the workspaceId; DevSpace automatically compares against the last shown checkpoint and advances that checkpoint after rendering the aggregate diff.

Shell Use

The shell tool is for commands that belong in a terminal:

  • tests
  • builds
  • git inspection
  • package scripts
  • environment checks

File writes should go through the edit/write tools rather than shell redirection, heredocs, tee, sed -i, or generated scripts.