Skip to main content

Agent Tutorial

In this tutorial, you will register a small repository, ask a coding agent to plan a TypeScript and React TODO app, create a Tasq issue from that plan, and follow the work through to a GitHub pull request.

Complete Install first.

Prerequisites​

  • The tq command is installed and available on your PATH.
  • tq service start is running. Confirm it with tq service status.
  • Codex CLI is installed and authenticated for GitHub, or Claude Code is installed and authenticated. You can also perform the tq commands yourself when neither agent is available.
  • GitHub CLI gh is installed and authenticated. Confirm it with gh auth status.
  • Git and a GitHub account are available.

1. Register the Tutorial Project​

Fork and Clone tasq-todo​

Fork version-1/tasq-todo on GitHub, then clone your fork. Replace <your-account> with your GitHub account name.

git clone https://github.com/<your-account>/tasq-todo.git
cd tasq-todo

You can use your own repository instead. Use a project key that is unique and easy to recognize in Tasq.

Add the Project to Tasq​

Register the repository and validate its workflow.

tq project add --key tasq-todo .
tq project check tasq-todo

tq project add links the current repository to the project key. It also creates a default WORKFLOW.md only when the repository does not already have one.

Minimal Permission Setup​

Before queuing work, allow Codex to write to this tutorial repository and its Git metadata. Add the following minimal profile to ~/.codex/config.toml, replacing /absolute/path/to/tasq-todo with the path of your clone.

[projects."/absolute/path/to/tasq-todo"]
trust_level = "trusted"

default_permissions = "tasq_todo"

[permissions.tasq_todo]
description = "Allow Codex to work in the Tasq tutorial repository."
extends = ":workspace"

[permissions.tasq_todo.filesystem.":workspace_roots"]
"." = "write"

[permissions.tasq_todo.workspace_roots]
"/absolute/path/to/tasq-todo" = true
"/absolute/path/to/tasq-todo/.git" = true

This is the smallest setup for the tutorial checkout. Add only the specific tool cache directories that your workflow needs; see Codex Autonomy Setup for command permissions and broader configurations.

Allow Tutorial Commands with Rules​

Allow the commands that the agent needs through Codex Rules. This lets it use tq to create and manage tutorial issues, and gh to inspect or create the pull request. Add the following to ~/.codex/rules/default.rules (or to the trusted project's .codex/rules/default.rules):

prefix_rule(
    pattern = ["gh", "pr", "create"],
    decision = "allow",
    justification = "Creating the tutorial pull request is an expected workflow step.",
)

prefix_rule(
    pattern = ["gh", "pr", ["view", "list", "status", "diff", "checks"]],
    decision = "allow",
    justification = "Inspecting tutorial pull requests is safe.",
)

prefix_rule(
    pattern = ["gh", "repo", ["view", "list"]],
    decision = "allow",
    justification = "Inspecting GitHub repository information is safe.",
)

prefix_rule(
    pattern = ["tq"],
    decision = "allow",
    justification = "The tq CLI is required for the Tasq tutorial workflow.",
)

Choose the allowlist command by command for your own workflow; do not allow all gh commands broadly. Use Tasq's tasq-dev.rules as a reference for selecting commands. After configuring the Rules, follow Verify Command Permission Coverage to check the complete Tasq lifecycle before queuing the tutorial work.

2. Understand WORKFLOW.md​

WORKFLOW.md is the project-level contract that tells Tasq and its agents how to run work in that repository. It combines runtime settings with the task instructions given to the agent.

The tasq-todo WORKFLOW.md demonstrates both parts:

  • Its front matter configures polling, the .worktrees/agents workspace root, agent limits, and the Codex app-server command.
  • Its body gives every agent the issue title, description, and a required flow: inspect scope, create an isolated branch or worktree, make a focused change, verify it, create a pull request, leave a handoff comment, and move the issue to review.

Copy this file into your own project as a starting point, then replace commands, test expectations, and workspace settings with ones that fit your repository. Use Workflow Configuration for workflow resolution and override details.

3. Plan Work and Create an Issue​

Install the tasq-cli Skill for Codex​

The optional tasq-cli skill gives Codex a focused reference for project, issue, workflow, service, and log commands. Install it once, then restart Codex so it loads the new skill.

python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo version-1/tasq \
  --path .agents/skills/tasq-cli

Claude Code is a valid alternative. It can use the same tq commands without this optional skill; include the command-oriented request below in your prompt and refer to the tq CLI reference when needed.

Create a Plan in Plan Mode​

Start Codex in plan mode in the tasq-todo directory. With Claude Code, use its plan mode when available; otherwise, use the same prompt and explicitly ask it not to edit files.

Send the following prompt. It asks the agent to read the prepared plan and use the installed tq command to turn it into Tasq issues, rather than copying the plan into the prompt or only describing the issues in prose.

Read this plan:
https://github.com/version-1/tasq-todo/blob/main/docs/plan.md

Use `tq issue create` to turn the plan into Tasq issues for project key
`tasq-todo`. Create the issues in implementation order, record dependencies
with `--dependency` where needed, and include the relevant plan details in each
issue description. Do not implement the plan. Report every created issue ID
when you finish.

In normal work, first have Codex or Claude Code inspect your own repository and produce a plan. Then adapt this prompt to create issues from that approved plan.

Confirm that the issues exist:

tq issue list --project tasq-todo

4. Inspect and Queue the Issue in the Web UI​

Open the local Web UI:

tq web

Use the project and issue list to select tasq-todo, then open the issue you just created. Check the title, description, plan, status, comments, and activity before allowing an agent to run it.

When the issue is ready, move it to ready in the UI. You can make the same transition from the CLI:

tq issue ready <issue-id>

5. Follow Agent Execution​

Tasq runs only ready issues whose dependencies have been resolved. An issue created with --dependency <issue-id> remains out of the runnable queue until that dependency reaches a terminal state. This lets you split a larger change into safe, ordered pieces instead of asking one agent to do everything at once.

Keep the issue detail page open. Use its Activity and comments to follow status changes, run events, worktree information, and the agent's handoff.

Recover a Blocked Codex Run​

If a Codex run becomes blocked, open the issue Activity tab and copy the thread ID from the latest run. From the repository checkout, resume that exact session:

codex resume <thread-id>

For a more autonomous setup that reduces repeated approval waits, follow Codex Autonomy Setup. For recovery details and alternatives such as codex resume --last, see Recover a Blocked Session.

6. Confirm the Pull Request​

When the agent completes the issue, confirm that the issue activity or comments link to a GitHub pull request. Review the change and its reported verification before merging.

If an issue does not reach review and becomes blocked or another unexpected status, first inspect the comments in the Web UI to identify the reported cause. In many cases, Codex was not allowed to run a required command or did not have sufficient permissions. Review Codex Autonomy Setup and adjust the command and permission configuration before retrying. If that does not resolve the problem, Recover a Blocked Session may help you continue the affected Codex run.

You do not need to wait for every issue in Tasq before applying this workflow to your own project. Start with one completed pull request, then register more projects as needed. Tasq becomes especially useful when it tracks several projects and their independent queues at the same time.