Replit Agent

Replit Agent is a lightweight, event-driven system that automatically executes tasks in response to changes in a Replit project. It runs as a background service within a Replit workspace, triggered by file modifications, scheduled intervals, or external API calls. It matters when you need consistent, reliable automation—such as building and deploying a web app on every git push, running tests after code edits, or synchronizing data between a database and a cloud storage bucket—without manual intervention or complex CI/pipeline setup.

Managing Replit Agent Configuration

Replit Agent uses a single configuration file, replit.agent, located in the root of a Replit project. This file defines the agent’s behavior, including which commands to run, when to run them, and how to handle their outputs.

{
  "version": 1,
  "triggers": [
    {
      "type": "file",
      "paths": ["*.py", "src/**/*.js"],
      "debounce": 500,
      "on": "change"
    },
    {
      "type": "schedule",
      "cron": "0 3 * * *",
      "on": "run"
    },
    {
      "type": "webhook",
      "path": "/api/agent/trigger",
      "method": "POST",
      "auth": {
        "type": "bearer",
        "token": "abc123xyz"
      }
    }
  ],
  "tasks": [
    {
      "name": "build",
      "command": "npm run build",
      "env": {
        "NODE_ENV": "production",
        "CI": "true"
      },
      "runOn": ["file", "schedule"]
    },
    {
      "name": "test",
      "command": "pytest tests/",
      "runOn": ["file"],
      "timeout": 30000,
      "onError": "notify"
    },
    {
      "name": "deploy",
      "command": "npm run deploy",
      "runOn": ["schedule"],
      "depends": ["build"],
      "onSuccess": "log",
      "onError": "slack"
    }
  ],
  "notifications": {
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/...",
      "channel": "#replit-deployments"
    },
    "email": {
      "to": "[email protected]",
      "from": "[email protected]"
    }
  }
}

The version field must be 1 for the current schema. The triggers array defines event sources: file changes, cron schedules, or HTTP webhook endpoints. Each trigger can be associated with one or more task names via the runOn field.

Responding to File Changes

When a file matching a file trigger’s paths pattern changes, Replit Agent waits for a debounce interval before executing all tasks listed in runOn. This prevents multiple rapid file edits from triggering redundant runs.

For example, saving a .py file in a project with replit.agent as above starts a 500ms debounce. If a developer saves app.py, then utils.py, then main.py within 400ms, only one test task runs, not three.

The on field specifies the event type: change (file modified), create (file added), delete (file removed), or rename (file renamed). These events are detected via inotify on Linux, and are reported by the Replit runtime kernel.

If a file trigger is not debounced, and multiple files change simultaneously, the agent processes them in order, with each change triggering the associated tasks in sequence. This allows for fine-grained control: a create trigger can be used to initialize a new module, while a change trigger runs tests on all Python files.

Scheduling Tasks with Cron

The schedule trigger uses standard cron syntax to define recurring intervals. The cron field accepts a five-field expression: minute, hour, day of month, month, day of week.

A cron value of "0 3 * * *" runs the associated tasks every day at 3:00 AM UTC.

When a schedule trigger fires, it queues a task execution. If a task is already running, the new execution is enqueued and runs after the current one completes.

Tasks can be run on multiple triggers. For instance, the build task runs on both file and schedule triggers, so it executes after every file change and daily at 3 AM.

Handling Webhook Triggers

The webhook trigger listens for HTTP POST requests on a specified path. The agent validates the auth field if provided.

If auth.type is bearer, the agent checks for a Authorization: Bearer <token> header in the request. If the token does not match auth.token, it returns a 401 Unauthorized response.

POST /api/agent/trigger HTTP/1.1
Host: my-project.replit.com
Authorization: Bearer abc123xyz
Content-Type: application/json

{
  "source": "github",
  "ref": "refs/heads/main"
}

On success, the agent responds with 200 OK and a JSON body indicating the task IDs of the triggered tasks.

Webhook triggers can pass data into the tasks via the body field of the trigger definition, which maps the incoming JSON to task environment variables.

{
  "type": "webhook",
  "path": "/api/agent/trigger",
  "body": {
    "source": "github",
    "ref": "refs/heads/main",
    "commit": "abc123"
  },
  "runOn": ["file", "schedule"]
}

This injects SOURCE=github, REF=refs/heads/main, and COMMIT=abc123 into the environment of every task that runs due to this webhook.

Defining and Running Tasks

Each task in the tasks array defines a unit of work: a command to execute, environment variables, a timeout, and execution policies.

The command field runs a shell command. It can be a single string or an array of strings for complex execution.

{
  "name": "lint",
  "command": [
    "eslint",
    "src/",
    "--fix",
    "--max-warnings=0"
  ],
  "runOn": ["file"],
  "timeout": 15000
}

The timeout field sets a maximum execution time in milliseconds. If the command runs longer than this, the agent kills the process with SIGTERM, waits 5 seconds, then sends SIGKILL.

If a task fails, Replit Agent logs the output to a file named logs/<task-name>.log in the project root. The log includes the full command, environment, and stdout/stderr interleaved.

Tasks can depend on other tasks. The depends field lists task names that must complete successfully before the current task runs.

{
  "name": "deploy",
  "command": "npm run deploy",
  "runOn": ["schedule"],
  "depends": ["build"],
  "onSuccess": "log",
  "onError": "slack"
}

If build runs but fails, deploy does not start. If build succeeds, deploy runs. The onSuccess and onError fields determine how the agent reports the result.

Notifications: What Happens When Tasks Run

Notifications are sent after a task completes, based on its outcome.

The notifications section defines named notification channels: slack, email, webhook, or console.

For slack, the agent sends a JSON payload to the webhookUrl using application/json with the following structure:

{
  "text": "✅ Task 'deploy' succeeded",
  "attachments": [
    {
      "title": "Task: deploy",
      "text": "Running on project: my-app",
      "fields": [
        { "title": "Duration", "value": "12.3s", "short": true },
        { "title": "Status", "value": "Success", "short": true }
      ],
      "color": "#36a64f"
    }
  ]
}

For email, the agent uses sendmail or SMTP to deliver the message with subject and body derived from the task result.

If onError is set to notify, the agent sends a notification on failure, regardless of the notifications configuration.

Error Handling and Failure Modes

Replit Agent silently fails when a task’s command exits with a non-zero code.

If a task’s command field is invalid or missing, the agent logs:

ERROR: Task 'build' failed to start: command 'npm run build' not found

The env object in a task is applied as environment variables. If env.NODE_ENV is set to production, the NODE_ENV variable is available to all processes launched by the task.

When a task depends on another, and that dependency fails, the agent logs:

INFO: Task 'deploy' waiting for 'build' to complete...
ERROR: Task 'build' failed: exit code 1
INFO: Task 'deploy' skipped: dependency 'build' failed

The onError field supports three values: notify, log, and slack.

• notify: sends a notification using the configured channels.
• log: appends a failure message to logs/<task-name>.log.
• slack: sends a detailed Slack message with the task’s output.

If onError is set to slack, the agent sends a Slack message even if the task completes successfully.

Advanced: Task Dependencies and Execution Order

Tasks can have multiple runOn triggers and multiple depends tasks. The agent resolves the execution graph at runtime.

For example:

{
  "name": "migrate",
  "command": "python manage.py migrate",
  "runOn": ["schedule"],
  "depends": ["build", "test"]
}

This task runs daily, but only after both build and test have completed successfully. If build runs every file change and test runs on every file change, migrate runs only when both build and test have finished their latest runs.

The agent maintains a queue of task executions. Each task has an ID, and the agent logs the execution timeline.

When a schedule trigger fires, it creates a new task execution with a unique ID. Subsequent schedule events can create overlapping executions.

If a task fails and onError is notify, the agent sends notifications immediately. If onError is log, it appends to the log file but does not send an alert.

Debugging and Logs

Logs are written to logs/ in the project root. Each task has its own log file: logs/build.log, logs/test.log, etc.

The agent itself logs to logs/replit-agent.log, which includes:

• Startup messages
• Trigger events
• Task scheduling and execution
• Error and warning messages

A common failure mode is a missing replit.agent file. When missing, the agent runs with default configuration: it listens for file changes in *.js, *.py, *.ts, and runs npm run build on every change.

Another sharp edge: if the tasks array contains a task with a depends list but one of the dependencies is missing, the agent logs:

WARNING: Task 'deploy' depends on 'build', but task 'build' not found in configuration.

When a webhook trigger receives a request with invalid JSON, the agent logs:

ERROR: Invalid JSON in webhook request body: unexpected token '}' at line 10, column 5

The agent uses jsonc parsing, so comments are allowed in replit.agent.

Summary

Replit Agent orchestrates project automation through a declarative, event-driven model. It responds to file changes, schedules, and HTTP calls with configurable tasks that can run in sequence, depend on each other, and report outcomes through multiple channels. The replit.agent file is the source of truth, and its structure—version, triggers, tasks, notifications—forms a predictable, composable system. It succeeds when the project runs the right commands at the right time, and fails when a task exits with an unexpected code or a trigger misses its target.

This page was rewritten on 11 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.