Code Generation

• Code Generation
  • How It Works
  • Triggering Code Generation
    • From Chat
    • From Telegram or Teams
    • From Linear (Issue Assignment)
    • From Automations
  • What You See
    • Real-Time Progress
    • In Your Inbox
  • Working with Existing Branches
  • Branch Naming
  • Under the Hood
    • Isolated Worktrees
    • Why Not GitHub MCP?
    • Agent Security
    • Project Skills
  • Tips
  • Status Reference

Themis can write code for you — implementing features, fixing bugs, writing tests, or refactoring — and submit the changes as a pull request on GitHub. Just describe what you want in plain language.

How It Works

1. You describe the change you want (in chat, Telegram, or Teams)
2. Themis clones your project, creates a branch, and makes the changes
3. It runs linting, commits, pushes, and opens a PR
4. You review the PR on GitHub

The entire process runs in the background. You’ll see real-time progress updates in chat and can continue working while Themis codes.

Triggering Code Generation

From Chat

Ask the agent directly:

“Implement a user profile page with avatar upload and timezone selector”

“Fix the N+1 query in the reviews controller”

“Add unit tests for the AutomationSchedulerJob”

The agent will recognize this as a code task and start the generation pipeline.

From Telegram or Teams

Mention the bot in a channel or DM:

@themis implement pagination for the activity feed

@themis fix the broken date formatting in the activity feed

From Linear (Issue Assignment)

Assign a Linear issue to the Themis bot and it will automatically start implementing it. This is the most natural workflow for engineering teams — just assign the ticket like you would to any team member.

1. Create or open an issue in Linear with a clear description
2. Assign it to Themis
3. Themis reads the issue title, description, and any linked context, then starts coding

This works with your existing sprint workflow — triage issues, assign the straightforward ones to Themis, and review the PRs that come back.

From Automations

Event-triggered automations can also generate code. For example, you could set up an automation on Linear → Issue assigned that triggers code generation whenever an issue is assigned to the bot.

What You See

Real-Time Progress

A progress bar appears in your chat showing each step:

Queued → Cloning → Analyzing → Generating → Testing → Linting → Pushing → Creating PR

Each step shows a spinner while active, then a checkmark when complete. If linting finds warnings, you’ll see a warning icon. If anything fails, an error message appears.

In Your Inbox

Code generations appear under Signals > Code in your inbox. Each entry shows:

• Title and project name
• Branch name and progress status
• PR link once created
• Files changed — count of created, modified, and deleted files
• AI-generated summary explaining the changes and motivation
• Reasoning log — expand to see the agent’s thinking, tool calls, and decisions
• Metadata — duration, cost, commit message

Working with Existing Branches

By default, Themis creates a new branch for each code generation. You can also ask it to work on an existing branch:

“On the feat/user-profiles branch, add email validation to the registration form”

This is useful for iterative development — make an initial request, review the PR, then ask for follow-up changes on the same branch.

Branch Naming

Branches follow the convention themis/<type>/<description>:

Type	When Used
feat	New features
fix	Bug fixes
refactor	Code restructuring
chore	Maintenance tasks
docs	Documentation
test	Test additions

Under the Hood

Isolated Worktrees

Each code generation runs in its own git worktree — an isolated copy of the repository. This means:

• No conflicts with your working tree. Themis never touches your local checkout or any in-progress branches.
• Parallel generations are safe. Multiple code generations can run simultaneously on different branches without interfering with each other.
• Clean environment. Each worktree starts from a fresh checkout of the base branch, so there’s no risk of leftover state from previous runs.

Worktrees are automatically cleaned up after the PR is created (or if the generation fails).

Why Not GitHub MCP?

You might wonder why Themis doesn’t use the GitHub MCP server to create files and commits through the API. The worktree approach is deliberately chosen over API-based file manipulation:

• The agent gets a real development environment. It can read the full project structure, run tools, check imports, and understand context — not just create files blind through an API.
• Standard git workflow. Changes go through git add, git commit, git push — the same flow a developer uses. This means proper diffs, blame history, and merge behavior.
• Security sandboxing. The agent runs inside a sandboxed environment with controlled shell access. Dangerous operations (file deletion outside the worktree, privilege escalation, secret access) are blocked by security hooks.
• Skill discovery. The agent reads your project’s .claude/ directory, CLAUDE.md, and any skill files to understand your conventions before writing a single line of code.

Agent Security

During code generation, the agent operates under strict constraints:

• Path containment — Can only modify files within the worktree directory
• No git operations — Branch creation, commits, and pushes are handled by the job, not the agent
• Blocked commands — rm -rf, chmod, curl to external hosts, environment variable access, and similar dangerous operations are intercepted
• Sandboxed execution — In production (Docker), the container provides additional isolation; locally, bwrap restricts filesystem access

Project Skills

If your project has a .claude/ directory with skills (like coding conventions, architecture guides, or test patterns), Themis discovers and loads them automatically. The agent reads:

• CLAUDE.md — Project-level instructions, tech stack, conventions
• .claude/skills/ — Specialized knowledge files (e.g., testing patterns, Hotwire conventions)
• Portable skills — Cross-project skills from lib/skills/ are copied into the worktree for the agent to use

This ensures generated code follows your project’s specific patterns — not generic boilerplate.

Tips

Be specific about requirements. “Add a search feature” is vague. “Add full-text search to the conversations index page using pg_trgm, with a Stimulus controller for debounced input” gives much better results.

Review the reasoning log if the generated code doesn’t match expectations. It shows exactly what the agent understood and why it made certain decisions.

Iterate on the same branch for complex features. Start with the core implementation, review it, then ask for refinements. Each follow-up builds on the previous changes.

Status Reference

Status	Meaning
Pending	Queued for processing
Cloning	Setting up git worktree
Analyzing	Reading project context and skills
Generating	Writing code changes
Testing	Running tests (if configured)
Linting	Checking code style
Pushing	Committing and pushing to remote
Creating PR	Opening pull request on GitHub
Completed	PR created successfully
No Changes	Agent determined no code changes were needed
Failed	Error occurred — check the error message