Second Workflow: Let It Change Code

Set up a worktree

If this repository already has a worktree that you develop in and have run the project in, skip to step 2.

If not, create one now. Two tasks running at the same time each need a workspace. The primary repository counts as one, so one more git worktree is enough. For the reasoning, see Workspaces.

From the root of the primary repository, run the following command, replacing my-app with the name of your project directory:

git worktree add ../my-app-wt-1 -b wt-1

This creates a my-app-wt-1 directory next to the primary repository and checks out a new branch, wt-1, in it. That branch is only a placeholder. When a task starts, CodeDAG switches this directory to the task branch.

The new directory contains only version-controlled files. If your project needs dependencies installed before its tests can run, such as node_modules or a Python virtual environment, install them in the new directory as you normally would. Copy over uncommitted local configuration files such as .env as well. Tasks 2 and 3 run tests in their own workspaces, and without these, the task that runs in the worktree can't run its tests.

Register the worktree with CodeDAG

If you chose 1 or 2 for Select your repository setup method in the quickstart, you can skip this step too.

If you chose 4, go back to the root of the primary repository and run initialization again:

cdg init

It asks a few questions in order, and your answer to the first one differs from the quickstart:

1. Select your repository setup method: Choose 1. I have set up git worktrees for this project. CodeDAG finds this repository's worktrees automatically, so you don't type any paths, and then asks you to select the ones to register as replicas. The my-app-wt-1 worktree you just created is selected by default, so press Enter to confirm. Worktrees that Claude Code and Codex created for their own sessions aren't selected by default.
2. File ".codedag/.gitignore" already exists. How would you like to handle this file?: Choose 3. Keep All. The settings and template files in .codedag/ were generated during the quickstart, and Keep All leaves them all as they are. The local settings file is kept as well, so this time you aren't asked about a default agent.
3. Update maxConcurrency to 2?: The project now has two workspaces, but the concurrency limit you kept is still 1, so initialization asks whether to change it to 2. The default is Yes, so press Enter.

If you didn't install the CodeDAG Guide plugin during the quickstart, you're asked once more whether to install it. Answer whichever way suits you. When initialization finishes, the output begins like this:

✔ Project initialized successfully!

  Project Repository: /Users/you/my-app
  Project Git workflow stays unchanged.
  Associated Replica Repositories:
    - /Users/you/my-app-wt-1

The worktree's path is listed under Associated Replica Repositories, which means it's now registered as a workspace for this project.

Answering Yes to the concurrency question brings the limit in the project settings in line with the number of workspaces. The workflow file in the next step still sets maxConcurrency: 2 explicitly, so this workflow allows two tasks to run at once no matter what the project settings say. To use clones instead of worktrees, set up more replicas, or edit the concurrency value in your local settings directly, see Run in Parallel with Workspaces.

Write the workflow file

Create .codedag/dags/two-small-changes.yaml, pick the version for the agent you want to use, and paste it in as is. The two versions differ only in each task's agent and mode.

maxConcurrency: 2

tasks:
  - id: 1
    title: Pick two TODOs
    agent: claude
    mode: bypassPermissions
    prompt: |
      Goal:
      Find the two TODOs in this project that are quickest to finish, and write a short implementation plan for each so that two later sessions can implement them separately.

      Details:
      - Filter the TODOs by my role and area of responsibility. They can come from TODO or FIXME comments in the code, to-do lists in the docs, skipped tests, or an issue tracker you have access to, such as GitHub Issues, Linear, or Jira.
      - If you can't find suitable TODOs, propose two small changes instead, based on what this project is for, its current state, and my responsibilities.

      Completion criteria:
      Write the plan to docs/plans/two-small-changes.md (overwrite the file if it already exists), in two sections titled "First item" and "Second item". In each section, state:
      - Goal: what to achieve, in a sentence or two.
      - Affected files: the paths of the files to modify or add, including test files.
      - Completion criteria: what counts as done, including the minimal tests to write first and the command that runs them.

      Constraints:
      - Don't create or modify any file other than this plan.

  - id: 2
    title: Implement the first item
    dependencies: [1]
    agent: claude
    mode: bypassPermissions
    prompt: |
      Goal:
      Implement the TODO described under "First item" in docs/plans/two-small-changes.md.

      Context and required reading:
      - docs/plans/two-small-changes.md is the plan written by the previous task. Its "First item" section states the goal, the affected files, and the completion criteria.

      Completion criteria:
      - Meet the completion criteria stated under "First item": write the minimal tests first, then implement until they pass.

      Constraints:
      - Modify only the files listed under "First item". Don't modify the plan file, and don't implement anything from "Second item".

      Notes:
      - Another session is implementing "Second item" on a different branch at the same time, and you can't see its changes. CodeDAG merges the two results afterward.

  - id: 3
    title: Implement the second item
    dependencies: [1]
    agent: claude
    mode: bypassPermissions
    prompt: |
      Goal:
      Implement the TODO described under "Second item" in docs/plans/two-small-changes.md.

      Context and required reading:
      - docs/plans/two-small-changes.md is the plan written by the previous task. Its "Second item" section states the goal, the affected files, and the completion criteria.

      Completion criteria:
      - Meet the completion criteria stated under "Second item": write the minimal tests first, then implement until they pass.

      Constraints:
      - Modify only the files listed under "Second item". Don't modify the plan file, and don't implement anything from "First item".

      Notes:
      - Another session is implementing "First item" on a different branch at the same time, and you can't see its changes. CodeDAG merges the two results afterward.

maxConcurrency: 2

tasks:
  - id: 1
    title: Pick two TODOs
    agent: codex
    mode: yolo
    prompt: |
      Goal:
      Find the two TODOs in this project that are quickest to finish, and write a short implementation plan for each so that two later sessions can implement them separately.

      Details:
      - Filter the TODOs by my role and area of responsibility. They can come from TODO or FIXME comments in the code, to-do lists in the docs, skipped tests, or an issue tracker you have access to, such as GitHub Issues, Linear, or Jira.
      - If you can't find suitable TODOs, propose two small changes instead, based on what this project is for, its current state, and my responsibilities.

      Completion criteria:
      Write the plan to docs/plans/two-small-changes.md (overwrite the file if it already exists), in two sections titled "First item" and "Second item". In each section, state:
      - Goal: what to achieve, in a sentence or two.
      - Affected files: the paths of the files to modify or add, including test files.
      - Completion criteria: what counts as done, including the minimal tests to write first and the command that runs them.

      Constraints:
      - Don't create or modify any file other than this plan.

  - id: 2
    title: Implement the first item
    dependencies: [1]
    agent: codex
    mode: yolo
    prompt: |
      Goal:
      Implement the TODO described under "First item" in docs/plans/two-small-changes.md.

      Context and required reading:
      - docs/plans/two-small-changes.md is the plan written by the previous task. Its "First item" section states the goal, the affected files, and the completion criteria.

      Completion criteria:
      - Meet the completion criteria stated under "First item": write the minimal tests first, then implement until they pass.

      Constraints:
      - Modify only the files listed under "First item". Don't modify the plan file, and don't implement anything from "Second item".

      Notes:
      - Another session is implementing "Second item" on a different branch at the same time, and you can't see its changes. CodeDAG merges the two results afterward.

  - id: 3
    title: Implement the second item
    dependencies: [1]
    agent: codex
    mode: yolo
    prompt: |
      Goal:
      Implement the TODO described under "Second item" in docs/plans/two-small-changes.md.

      Context and required reading:
      - docs/plans/two-small-changes.md is the plan written by the previous task. Its "Second item" section states the goal, the affected files, and the completion criteria.

      Completion criteria:
      - Meet the completion criteria stated under "Second item": write the minimal tests first, then implement until they pass.

      Constraints:
      - Modify only the files listed under "Second item". Don't modify the plan file, and don't implement anything from "First item".

      Notes:
      - Another session is implementing "First item" on a different branch at the same time, and you can't see its changes. CodeDAG merges the two results afterward.

The file doesn't set executionMode, so the workflow uses the default isolated-branches mode. A few things in it are worth noting:

• maxConcurrency: 2 allows up to two tasks to run at the same time. The number of tasks that actually run at once also can't exceed the number of available workspaces. Here that's the primary repository plus one worktree, which makes exactly two. See maxConcurrency.
• Tasks 2 and 3 both set dependencies: [1]. Both wait for task 1 to finish and be accepted before they start, but neither depends on the other, so they start together as soon as task 1 is accepted.
• Tasks 2 and 3 read docs/plans/two-small-changes.md directly. Task 1 wrote that file on its own branch. After task 1 is accepted, CodeDAG merges its result into the task branches for tasks 2 and 3 before it starts them, so each can read the file in its own workspace from the start. For why a dependency is also a channel for passing information, see Dependencies.
• The two parallel tasks can change overlapping code. Tasks 2 and 3 each make their changes on their own task branch, so they don't affect each other while they run. If their results touch the same code when they're merged, CodeDAG first hands the conflict to an agent to resolve. See Merges and conflicts at join nodes. That's why task 1 doesn't have to avoid picking two TODOs that change the same place, and why the constraints on tasks 2 and 3 only confine each one to its own item.

Validate and submit

First, validate the workflow file:

cdg dag validate two-small-changes

✔ Validation passed: .codedag/dags/two-small-changes.yaml

Once it passes, submit the workflow and have the current terminal follow the logs:

cdg dag submit two-small-changes --attach

✔ Submitted successfully: .codedag/dags/two-small-changes.yaml

Queue position:
  #1  .codedag/dags/two-small-changes.yaml (now running in background)

📊 Following logs... (Ctrl+C to detach logs, Ctrl+\ to kill current workflow)

Task 1 runs first, in the primary repository. After it finishes and is auto-accepted, the start lines for tasks 2 and 3 appear in the logs one right after the other:

[Task   1] [2026-09-30 10:39:32] END: Pick two TODOs
[Task   2] [2026-09-30 10:39:36] START: Implement the first item
[Task   3] [2026-09-30 10:39:36] START: Implement the second item

From then on, the logs from the two tasks are interleaved. As in the quickstart, pressing Ctrl+C only stops the terminal from following the logs, and the workflow keeps running in the background.

Watch two tasks run in parallel

Open another terminal, go to the primary repository, and view the status board for this workflow:

cdg dag status two-small-changes --watch

While tasks 2 and 3 are running, the board looks like this:

[TZ: -04:00] 2026-09-30 10:39:39

Workflow: .codedag/dags/two-small-changes.yaml
  Phase: 📤 submitted
  Queue Position: 1
  Status: 🟢 in-progress
  Substatus: working

Submitted Tasks (2):
  🟢 [in-progress] [working]  Task 2: Implement the first item
  🟢 [in-progress] [working]  Task 3: Implement the second item

Reviewed Tasks (1):
  🤖☑️ [auto-accepted]  Task 1: Pick two TODOs

Progress: 1/3 tasks completed (33%), 1 reviewed

Task 1 has been auto-accepted and moved to Reviewed Tasks. Tasks 2 and 3 are both [in-progress] [working], each in its own workspace. To confirm where each one is running, look at the branch currently checked out in each workspace:

git worktree list

/Users/you/my-app       9a2b3bc [cdg/two-small-changes/t2-implement-the-first-item]
/Users/you/my-app-wt-1  9a2b3bc [cdg/two-small-changes/t3-implement-the-second-item]

The primary repository has been switched to task 2's branch, and the worktree to task 3's branch. Task branches are named cdg/<workflow-name>/t<task-id>-<title>. Both lines show the same commit, the one CodeDAG created for task 1 when it accepted that task. In other words, both tasks start from task 1's result.

Check the result and merge into the main branch

When both tasks finish, CodeDAG auto-accepts them and merges the two task branches into the integration branch, and the workflow as a whole is then auto-accepted. The terminal following the logs stops at that point, and the last line is:

✔ Workflow auto-accepted: .codedag/dags/two-small-changes.yaml

If the two tasks changed the same code, the merge into the integration branch produces a conflict, and CodeDAG first hands it to an agent to resolve. If it's still unresolved after three rounds, the workflow stops at on-hold and waits for you, and the line above doesn't appear. To resolve it, see Merge conflicts.

After the workflow finishes, the primary repository is left on the integration branch, and git branch --show-current prints cdg/two-small-changes/integration. Start by looking at the commits the integration branch has that main doesn't:

git log --oneline main..HEAD

ba8ab12 Merge task 3 into cdg/two-small-changes/integration
b99fcd0 Implement the first item
d6077f1 Implement the second item
9a2b3bc Pick two TODOs

When CodeDAG accepts a task, it commits the changes the task left behind to that task's branch, with the task title as the commit message. The merge commit at the top is the one CodeDAG created when it merged task 3's branch into the integration branch. Next, look at which files changed:

git diff main...HEAD --stat

Before you merge, read through the changes file by file, then run your project's tests on the integration branch. CodeDAG considers a task complete when the task agent has stopped working, and auto-accept doesn't look at test results either, so confirming that the changes are correct is up to you. The docs/plans/two-small-changes.md file that task 1 wrote is part of these changes too. If you don't want it on the main branch, delete it and commit first.

Once you're satisfied, you can merge the result into the main branch. On a team, that usually goes through a pull request. The integration branch was created from main and carries all the changes from this run, so create a branch of your own from it, push that branch to the remote, and open a pull request as usual. Name the branch according to your team's conventions. This example uses feat/two-small-changes:

git checkout -b feat/two-small-changes cdg/two-small-changes/integration
git push -u origin feat/two-small-changes
git checkout main

Pushing is up to you: CodeDAG itself never pushes to your remote repository or pulls from it. The last command puts the primary repository back on main, and it also determines where the next workflow starts. When a workflow starts running, it takes the commit checked out in the primary repository as its base, so if the primary repository is still on the integration branch or on this new branch, the next workflow builds on this run's result. See Task branches, the integration branch, and the base.

If you don't need code review, as in a personal project, you can also merge locally: run git checkout main to switch back to the main branch, then run git merge cdg/two-small-changes/integration. If main has no new commits in the meantime, this is a fast-forward merge. For other ways to merge, see Merge into the main branch.