Skip to main content
Tembo Hooks allow you to customize and extend Tembo’s behavior by running custom commands at certain points during execution of a task. This powerful feature enables you to integrate your existing development practices, CI/CD processes, and quality checks directly into Tembo’s automated workflow.

​
Overview

Tembo Hooks are configured through a .tembo.json file in your repository root. These hooks execute shell commands at predefined lifecycle events, giving you full control over how Tembo interacts with your codebase and development environment.

​
Configuration

Create a .tembo.json file in your repository root with the following structure: 
{
  "hooks": {
    "postClone": [
      "npm install",
      "echo 'Repository cloned and dependencies installed'"
    ],
    "prePush": [
      "npm run lint",
      "npm run test",
      "npm run build"
    ]
  }
}

​
Available Hooks

​
postClone

Executes immediately after Tembo clones your repository and before it begins working on the issue. Common use cases:
  • Install dependencies (npm install, pip install -r requirements.txt)
  • Set up development environment
  • Download required assets or configurations
  • Initialize database connections or test data
Example: 
{
  "hooks": {
    "postClone": [
      "npm ci",
      "cp .env.example .env.local",
      "npm run db:migrate"
    ]
  }
}

​
prePush

Runs after Tembo has made changes to your code but before pushing the changes and creating a pull request. Common use cases:
  • Run linting and formatting (eslint, prettier, black)
  • Execute test suites
  • Build the project to ensure no compilation errors
  • Run security scans or code quality checks
  • Generate documentation or update version files
Example: 
{
  "hooks": {
    "prePush": [
      "npm run lint:fix",
      "npm run test:unit",
      "npm run build",
      "npm run security:scan"
    ]
  }
}

​
Automatic Fix Mode

Set "autoFix": true at the root level of your .tembo.json to enable automatic error recovery. When a hook fails, Tembo will analyze the error output and attempt to fix the issue before retrying. 
{
  "hooks": {
    "prePush": ["npm run lint", "npm run test"]
  },
  "autoFix": true
}

​
Hook Execution Details

​
Execution Environment

  • Hooks run in the same Docker sandbox environment as Tembo
  • Commands execute in the repository’s root directory
  • All environment variables available to Tembo are also available to hooks
  • Commands run with the same permissions as the Tembo process

​
Error Handling

  • If any command in a hook fails (returns non-zero exit code), the hook execution stops
  • Hook failures are handled silently. If autoFix is enabled, Tembo will analyze the error output and attempt to fix the issues automatically

​
Command Execution

  • Commands are executed sequentially in the order they appear in the array
  • Each command runs in a separate shell session
  • Commands support shell features like piping, redirects, and environment variables
  • Multi-line commands can be written as single strings with semicolons or && operators

​
Advanced Example

A full-stack application with database, linting, testing, and build steps: 
{
  "hooks": {
    "postClone": [
      "npm ci",
      "docker-compose up -d postgres",
      "npm run db:migrate"
    ],
    "prePush": [
      "npm run lint",
      "npm run test",
      "npm run build"
    ]
  },
  "autoFix": true
}
Adapt the commands to your stack—the pattern works for any language or framework.

​
Best Practices

  • Keep commands fast — Use caching (npm ci), run only essential checks in prePush
  • Handle errors — Use set -e in shell scripts; provide meaningful error messages
  • Secure credentials — Use environment variables, never hardcode secrets in commands
  • Test locally first — Verify hooks work before committing; check Tembo’s execution logs

​
Troubleshooting

​
Common Issues

Hook Commands Not Found
  • Ensure required tools are installed in the postClone hook
  • Verify the command exists in the Docker environment Tembo uses
Permission Errors
  • Check that commands don’t require elevated privileges
  • Ensure file permissions allow the operations you’re trying to perform
Timeout Issues
  • Long-running commands may cause timeouts
  • Consider moving lengthy processes to background tasks or separate CI/CD pipelines

​
Debugging

  • Check Tembo’s execution logs in your dashboard for hook output
  • Add echo statements to track hook progress
  • Test commands individually in a similar environment before adding to hooks