Building Custom Agent Workflows with .cwt Directories

A bare prompt works fine for one-off tasks. Ask Claude Code to rename a variable, fix a type error, write a test - no special setup needed. But the moment your task depends on project conventions, deployment targets, API keys, or coordination between multiple agents, a bare prompt falls short.

Consider a deploy job. The agent needs to know which branch to build, where the artifacts go, what secrets to use, and what post-deploy checks to run. You could paste all of that into the prompt every time, but that's fragile and repetitive. A CLAUDE.md file in your repo helps, but it mixes agent-specific workflow instructions with general project context that human developers also read.

ClawTab's .cwt/ directory gives you a dedicated place for agent workflow configuration - separate from your codebase documentation, versioned alongside your project, and automatically wired into every job run. Each job gets its own subfolder with its own instructions, while shared context lives at the root level where every job can access it.

The .cwt/ directory lives at the root of your project, next to your src/, package.json, or Cargo.toml. Inside it, each job gets its own subfolder. Here's what a typical setup looks like:

myproject/
  .cwt/
    cwt.md              # shared context for all jobs (you write this)
    browse.sh           # auto-generated Safari automation helper
    send.sh             # auto-generated Telegram send helper
    deploy/
      job.md            # deploy-specific prompt (you write this)
      cwt.md            # auto-generated per-job context
    lint/
      job.md            # lint-specific prompt (you write this)
      cwt.md            # auto-generated per-job context
    review/
      job.md
      cwt.md

There are two files you write yourself and one that ClawTab generates:

• .cwt/cwt.md (root level) - shared context available to every job in the project. Write project-wide conventions, architecture notes, and common instructions here.
• .cwt/{job-name}/job.md - the prompt and instructions for one specific job. This is where you describe what the job should do.
• .cwt/{job-name}/cwt.md - auto-generated by ClawTab on save, settings change, or app startup. Contains job-specific metadata, tool references, and environment details.

If you don't set a job_name, ClawTab defaults to "default", placing files at .cwt/default/job.md.

The root .cwt/cwt.md file is your project's shared context - the information every job in this project needs regardless of what it's doing. Think of it as a CLAUDE.md scoped specifically to your automated workflows.

Good shared context includes:

• Project architecture - where the source lives, what the build system is, which directories matter
• Conventions - coding style, commit message format, branch naming, test expectations
• Environment details - which runtime version, which package manager, paths to config files
• Common constraints - "never modify files in vendor/", "always run tests before committing", "use pnpm, not npm"

Here's an example for a TypeScript monorepo:

# Project context

- Monorepo: pnpm workspaces
- Packages: apps/web (Next.js), apps/api (Fastify), packages/shared
- Build: pnpm turbo build
- Test: pnpm turbo test
- Lint: pnpm biome check --write
- Node 22, TypeScript strict mode
- Never edit generated files in dist/ or .next/
- Commit messages: imperative mood, no prefix

Keep it concise. The agent reads this on every run, so avoid verbose explanations. State facts, not tutorials.

Each job's job.md is the actual prompt - the task description that tells the agent what to do. This is where you get specific.

A deploy job might look like this:

# Deploy to staging

1. Pull latest from main
2. Run the full test suite: pnpm turbo test
3. If tests pass, build all packages: pnpm turbo build
4. Deploy apps/web to Vercel: vercel --prod
5. Deploy apps/api: docker build -t api . && docker push registry.example.com/api:latest
6. Run smoke tests: curl -f https://staging.example.com/health
7. Post results to Telegram using send.sh

A lint/fix job could be much simpler:

# Lint and fix

Run biome check --write on the entire codebase.
If there are unfixable errors, list them and stop.
If everything passes, commit the changes with message "fix: auto-lint".

The job.md content is passed directly to Claude Code as the prompt. ClawTab also includes it via an @ file reference so Claude has both the file context and the inline instructions. You can use markdown, numbered steps, conditional logic, references to other files in the project - anything you'd put in a Claude Code prompt.

When you save a Folder job or start the ClawTab desktop app, it generates (or regenerates) the per-job .cwt/{job-name}/cwt.md file. This auto-generated file contains metadata that changes between runs or depends on your ClawTab configuration:

• Job name and identifier
• Available helper scripts (browse.sh for Safari automation, send.sh for Telegram messaging)
• Environment variable names that will be available at runtime
• References to the shared context file

ClawTab also generates the helper scripts at the root .cwt/ level. browse.sh wraps Safari automation so your agent can fetch web pages, and send.sh wraps Telegram messaging so your agent can post status updates mid-run (if you have Telegram configured).

When a Folder job runs, ClawTab assembles everything into a single Claude Code invocation:

cd /projects/myapp && claude $'@.cwt/cwt.md @.cwt/deploy/cwt.md @.cwt/deploy/job.md\n\n<job.md content>'

The @ references tell Claude Code to read those files as context. The job.md content is also included inline as the prompt. The working directory is the project root (parent of .cwt/), not the .cwt/ directory itself, so all file paths in your instructions are relative to the project.

Secrets are injected as tmux environment variables - they never appear in the command string or in any file.

A single .cwt/ directory can hold as many jobs as you need. Each job is a subfolder with its own job.md and auto-generated cwt.md. All of them share the root .cwt/cwt.md context.

In ClawTab, you create multiple Folder jobs pointing to the same .cwt/ path but with different job_name values:

# Job 1: deploy
job_type: folder
folder_path: /projects/myapp/.cwt
job_name: deploy

# Job 2: lint
job_type: folder
folder_path: /projects/myapp/.cwt
job_name: lint

# Job 3: review
job_type: folder
folder_path: /projects/myapp/.cwt
job_name: review

Each job runs in its own tmux pane. ClawTab groups them under the same tmux window (named cwt-myapp), splitting panes when a window already exists. This means you can run deploy, lint, and review simultaneously as parallel agents - each with their own instructions but sharing the same project context.

This pairs well with agent swarms. Instead of running multiple copies of the same task, you run different specialized agents that each handle one aspect of your workflow.

Folder jobs support cron scheduling just like any other ClawTab job. This turns your .cwt/ configurations into recurring automated workflows.

Common patterns:

• Nightly lint pass - schedule a lint job for 2am every night. The agent runs biome/eslint, fixes what it can, and commits the result.
• Morning dependency review - a job that checks for outdated packages, reviews changelogs, and opens PRs for safe updates.
• Post-deploy smoke tests - trigger a test job after each deploy to verify the staging environment.
• Weekly code review - an agent that reviews the week's PRs and posts a summary to Telegram.

Because the instructions live in job.md files and the shared context in cwt.md, updating the workflow is just editing a markdown file. No pipeline YAML, no CI configuration language - just plain instructions the agent reads on every run.

Pair cron-triggered jobs with auto-yes mode to let them run completely unattended. The agent launches on schedule, ClawTab auto-accepts permission prompts, and you get a Telegram notification when it finishes.

There are three ways to give Claude Code project context. Each serves a different purpose:

	Bare prompt	CLAUDE.md	.cwt directory
Scope	Single run	All Claude Code sessions in the repo	ClawTab jobs in this project
Persistence	None	Versioned in repo	Versioned in repo
Audience	One-off task	Every developer + every agent	Automated agent workflows only
Per-job instructions	Inline in prompt	Not supported	Separate job.md per job
Shared context	Copy-paste	Automatic	Automatic via cwt.md
Auto-generated metadata	No	No	Yes (helper scripts, env, tools)
Cron support	No	No	Yes
Secret injection	Manual export	No	Automatic via tmux env

Use CLAUDE.md for general project conventions that benefit both human developers and ad-hoc Claude Code sessions. Use .cwt/ for structured, repeatable agent workflows that run on a schedule or are triggered from ClawTab. The two complement each other - your CLAUDE.md might say "use pnpm" and your .cwt/deploy/job.md says "run pnpm turbo build and deploy to Vercel".

For one-off tasks, a bare prompt is still the right tool. Don't over-engineer a .cwt/ directory for something you'll run once.

Here are four .cwt/ configurations for common development workflows:

Deploy

# .cwt/deploy/job.md
Pull main, run tests, build, and deploy to staging.
If any step fails, stop and report the error via send.sh.
On success, run smoke tests against staging and report results.

Lint and fix

# .cwt/lint/job.md
Run biome check --write on the entire codebase.
Commit any changes with message "fix: auto-lint".
If there are unfixable errors, list them in a Telegram message.

Code review

# .cwt/review/job.md
Find all PRs merged to main in the last 24 hours.
For each PR, review the diff for:
- Security issues (exposed secrets, SQL injection, XSS)
- Performance regressions (N+1 queries, missing indexes)
- Missing tests for new functionality
Post a summary to Telegram with findings per PR.

Test suite

# .cwt/test/job.md
Run the full test suite: pnpm turbo test
If any tests fail:
1. Read the failing test and the code it tests
2. Determine if the test is wrong or the code is wrong
3. Fix whichever is incorrect
4. Re-run the failing tests to confirm the fix
5. Commit with message "fix: repair failing tests"

Each of these shares the same root .cwt/cwt.md for project conventions, uses injected secrets for API tokens, and can be triggered manually from ClawTab or on a cron schedule.