tim

llmutils

Command-line utilities for managing context with chat-oriented programming and applying edits from language models.

Key Commands

• rmfilter: Analyzes import trees to gather related files, adds instructions, and prepares context for LLMs
• rmfind: Finds relevant files to use with rmfilter
• tim: Generates and manages step-by-step project plans using LLMs
• apply-llm-edits: Applies LLM-generated edits back to the codebase
• rmrun: Sends rmfilter output to an LLM and applies edits
• rmfix: Toolkit for fixing LLM-generated code when it doesn't apply cleanly

Tim Prompt Helpers

tim prompts can print reusable prompt text for CLI-driven workflows. For implementation work, use tim prompts implement <plan> to load a plan and instruct the agent to implement it while keeping the plan up to date.

Tim Chat

tim chat runs an arbitrary free-form prompt in Claude Code or Codex. Without workspace options, it behaves exactly as before and runs in the current working directory.

When you provide workspace options, tim chat participates in the full workspace roundtrip flow used by other tim workspace-aware commands. This includes workspace selection or creation, branch checkout, optional plan association, workspace sync, and optional committing at the end of the session.

Workspace options:

• -w, --workspace <id> to use a specific workspace
• --aw, --auto-workspace to automatically choose a workspace
• --nw, --new-workspace to create a new workspace
• --base <ref> to work against a specific branch or ref in the workspace
• --plan <plan> to associate the session with a plan and use that plan's workspace metadata
• --commit to commit changes after the session finishes
• --no-workspace-sync to disable workspace sync for the roundtrip

Examples:

tim chat --aw --plan 42 "Fix the bug"
tim chat -w my-workspace --base feature-branch "Review code"
tim chat --aw --base main --commit "Clean up imports"

Workspace Management

Use tim workspace list, tim workspace add, and tim workspace update to manage repository workspaces. Workspaces can be standard, primary, or auto: primary workspaces receive branch updates from origin after execution, while auto workspaces form the preferred pool for --auto-workspace.

tim workspace add [planIdentifier] [--primary | --auto] sets the initial type for a new workspace, and tim workspace update <id> [--primary | --no-primary | --auto | --no-auto] changes it later. When at least one auto workspace exists, commands such as tim agent --auto-workspace and tim generate --auto-workspace only choose from auto workspaces; otherwise they fall back to any non-primary workspace. See docs/multi-workspace-workflow.md for the full workflow.

Plan Auto-Completion Status

When all tasks in a plan are completed (via tim done, agent batch mode, or stub plans), the plan transitions to needs_review by default instead of done. This gives you a chance to review completed work before marking it fully done. Parent plans also auto-complete to needs_review when all children reach a work-complete state (done, needs_review, cancelled, or deferred).

Plans in needs_review satisfy dependency requirements, so downstream plans are not blocked. Workspace assignments and locks are preserved for needs_review plans and only released when the plan reaches done (whether via tim set, auto-completion with planAutocompleteStatus: done, or agent-driven completion).

To skip the review step and go directly to done, set the planAutocompleteStatus config option:

# tim.yml
planAutocompleteStatus: done # default: needs_review

Explicit status changes via tim set <id> --status done always go directly to done regardless of this setting.

When the agent is launched from the web UI (with --no-terminal-input), the final review always exits automatically after completion. If the review found issues, they are saved as reviewIssues on the plan and the status is set to needs_review. The user can then triage review issues from the web UI and re-run the agent to continue.

PR Status Monitoring

tim pr is a subcommand namespace for GitHub PR operations: