Feature: My Agent Tasks - EyevinnOSC/community GitHub Wiki
My Agent Tasks
My Agent Tasks is a feature in the OSC web console that lets you create and schedule automated AI agent tasks that run on your behalf. Instead of having your own machine running an AI agent on a schedule, OSC handles the execution for you in the cloud.
What You Can Do
- Create tasks with a natural language prompt that the agent will execute
- Choose between two agent runtimes: Claude Code (Anthropic) or Codex (OpenAI)
- Schedule tasks to run automatically (every 15 minutes, hourly, daily, weekdays, weekly)
- Optionally point tasks at a Git repository so the agent has access to your code
- Trigger tasks manually at any time with "Run Now"
- Manage tasks via the web console or MCP tools
Prerequisites
- An OSC account on a paid plan (Personal, Professional, or Business)
- An API key for your chosen runtime (Anthropic or OpenAI)
Agent Runtimes
OSC supports two agent runtimes. You select the runtime when configuring credentials and creating tasks.
Claude Runner (birme-claude-runner)
The original OSC agent runtime. Runs tasks using Claude Code CLI from Anthropic.
Supported credentials (choose one):
| Credential type | Secret name | Description |
|---|---|---|
| Anthropic API Key | anthropicapikey |
An sk-ant-... key from console.anthropic.com |
| Claude OAuth Token | claudeoauthtoken |
A token obtained via Claude's OAuth flow |
Best suited for: Tasks that benefit from Claude's reasoning, code generation, and OSC platform integration via MCP.
Codex Runner (birme-codex-runner)
A newer runtime that runs tasks using OpenAI Codex CLI.
Supported credentials:
| Credential type | Secret name | Description |
|---|---|---|
| OpenAI API Key | openaikey |
An sk-... key from platform.openai.com |
Best suited for: Tasks where you prefer OpenAI models (such as o3, gpt-4.1), or workflows already built around the Codex CLI and AGENTS.md conventions.
Runtime comparison
| Feature | Claude Runner | Codex Runner |
|---|---|---|
| AI provider | Anthropic | OpenAI |
| CLI | Claude Code | Codex CLI |
| Context file | CLAUDE.md |
AGENTS.md |
| Default model | claude-sonnet-4-5 |
codex-mini-latest |
| Custom models | Yes (Model field) |
Yes (Model field, e.g. o3-mini, gpt-4.1) |
| OSC MCP integration | Yes | Yes (via OscAccessToken) |
| Sandbox control | Via allowed/disallowed tools | Via Sandbox option |
| Credential types | Anthropic API key or Claude OAuth token | OpenAI API key only |
Getting Started
Step 1: Navigate to My Agent Tasks
Go to My Agent Tasks in the OSC web console.
The page includes an AI prompt bar at the top. You can type a natural language question or request (e.g. "Create a daily task that posts a Slack summary") and the inline AI assistant will help you manage your tasks without leaving the page. Suggested prompts based on your existing tasks are shown as clickable chips below the input.
Step 2: Configure Credentials
The first time you open the page you are prompted to configure your agent credentials. The page shows an onboarding hero with starter template cards below the setup form, so you can pick a common task type before you even enter your credentials.
For Claude Runner, choose one of:
- Anthropic API Key — an
sk-ant-...key from console.anthropic.com - Claude OAuth Token — a token obtained via Claude's OAuth flow
For Codex Runner, provide:
- OpenAI API Key — an
sk-...key from platform.openai.com
Enter the credential and click Save. The credentials are stored securely and used to run your tasks.
Once credentials are configured, a status bar at the top of the page shows the credential type. From there you can:
- Reconfigure — click to expand the setup form inline and enter new credentials
- Remove — opens a confirmation modal to delete stored credentials
Step 3: Create a Task
Starter templates: When you have no tasks yet, the page shows four built-in starter template cards. Click any card to open the Create Task modal with the prompt field pre-filled:
| Template | What it does |
|---|---|
| Code review assistant | Reviews open pull requests and flags issues with best practices, potential bugs, and security concerns |
| Dependency updater | Scans for outdated packages and opens update PRs after verifying tests pass |
| Test writer | Generates unit tests for recently changed code, covering happy path, edge cases, and error conditions |
| Documentation generator | Keeps README and API docs up to date with the current implementation |
You can edit the pre-filled prompt before saving. Starter templates appear until you have created at least one task.
Click Create Task and fill in:
| Field | Description |
|---|---|
| Name | Short identifier for the task |
| Description | What the task does (optional, for your reference) |
| Prompt | The instruction the agent will execute |
| Agent Type | Runtime to use: birme-claude-runner (default) or birme-codex-runner |
| Source URL | Git repository URL to give the agent code context (optional) |
| Git Token | Personal access token for private repositories (optional, write-only) |
| OSC Access Token | OSC API token for tasks that call OSC services via MCP. Choose from three modes: Managed (default) — OSC mints and stores a scoped token on your behalf; Paste — enter a token manually; Reference — select an existing Service Secret by name. Managed is recommended for most users. |
| Notification Email | Email address to notify when the task completes or fails (optional) |
| Schedule | When to run the task (choose a preset or enter a cron expression) |
Advanced Settings (click "Advanced Settings" to expand):
| Field | Description |
|---|---|
| Model | Model to use (e.g. claude-sonnet-4-5-20250514 for Claude Runner, o3-mini or gpt-4.1 for Codex Runner) |
| Max Turns | Maximum agent turns per run (default: 25, Claude Runner only) |
| Allowed Tools | Comma-separated tool allowlist (e.g., Read,Write,Edit, Claude Runner only) |
| Disallowed Tools | Comma-separated tool blocklist (e.g., Bash, Claude Runner only) |
| Sub Path | Subdirectory within the source repository to use as the working directory |
| Parameter Store | Name of a Parameter Store service instance to inject env vars into the task. The field shows an autocomplete list of your existing Parameter Store instances. You can also type a name directly. (optional) |
| Parameter store API key | The CONFIG_API_KEY for an encrypted parameter store. Appears only when a Parameter Store is selected. This field is write-only — it is never pre-filled when editing an existing task. Required if the store was created with encrypted secrets enabled (the default). |
Schedule type:
Tasks have two scheduling modes, controlled by the Schedule Type field:
| Schedule Type | Behaviour |
|---|---|
| Cron (default) | Fired automatically by the scheduler according to the cron expression |
| Manual | Never auto-fired. Run it on demand using Run Now or the run-agent-task MCP tool |
Use the Manual type for tasks that should only run when explicitly triggered — for example, one-off data migrations, on-demand reports, or tasks that need human review before each run.
Schedule presets (cron tasks):
| Preset | UTC cron expression |
|---|---|
| Every 15 minutes | */15 * * * * |
| Hourly | 0 * * * * |
| Daily at 9am UTC | 0 9 * * * |
| Weekdays at 9am UTC | 0 9 * * 1-5 |
| Weekly Mon at 9am UTC | 0 9 * * 1 |
Schedule times are stored in UTC but displayed in your local timezone. When you select a preset or enter a custom cron expression, the modal shows a live preview of the human-readable schedule and the next scheduled run time in your local timezone.
Click Create to save the task.
Scheduling note: New cron tasks do not fire immediately on creation. The first execution occurs at the first scheduled cron slot that falls after the task was created. For example, a task created at 9:05 UTC with a daily
0 9 * * *schedule will first run the following day at 9:00 UTC.
Step 4: Run or Monitor Tasks
Tasks run automatically on their schedule. You can also:
- Click the Refresh button at the top of the tasks table to reload the task list and see the latest run statuses
- Click the Run Now button on any task to trigger it immediately
- Check the Last Run and Next Run timestamps in the task table
- Click the Last Run status chip to open the run history for that task
- Edit or delete a task from the actions column
Token expiry warning: If the OSC Access Token used by one or more of your tasks is expiring within 7 days, a warning banner appears at the top of the Agent Tasks page listing the affected task names. Click Rotate token in the banner to go to your API settings and regenerate the token before it expires. Keeping the token current prevents future runs from failing with authentication errors.
The home dashboard shows a warning indicator on the Agent Tasks stat tile when one or more tasks have a failed last run status. The badge displays the count of failing tasks and links directly to the Agent Tasks page so you can investigate quickly.
Auto-disable on repeated failures: If a task fails 5 times in a row, OSC automatically disables it to prevent runaway costs. The task shows an Auto-disabled reason in the table. To resume it, edit the task and re-enable it (which also resets the failure counter).
Step 5: View Run History and Logs
To see the execution history for a task, open the actions menu and click View Runs. Alternatively, click the Last Run status chip in the task table.
The run history modal shows each recorded execution with:
- Status (Completed, Failed, Running, or Cancelled)
- Started At timestamp in your local timezone
- A View Logs button for each run
- A Cancel button for runs that are currently Running — click Cancel to stop the agent mid-execution. A confirmation dialog appears before the run is cancelled.
OSC stores up to 50 run history entries per task. Older entries are pruned automatically when the limit is reached.
Clicking View Logs opens the log viewer for that run. Logs are paginated and can be downloaded as a plain text file. If a run's logs have expired (typically 2-7 days after completion), the log viewer shows an expiry notice instead.
Authentication failure callout: If a run failed because the OSC Access Token could not authenticate (e.g. it expired or was rotated without updating the task), the log viewer shows a warning banner above the raw logs:
OSC Access Token expired or invalid. This run failed because the OSC Access Token could not be authenticated. Rotate the token to fix future runs. [Manage tokens]
Click Manage tokens to go directly to your API settings page and rotate the token.
Importing an App from GitHub
The Import button on the My Apps page lets you bring an existing GitHub repository into OSC as a managed My App. The import runs an AI agent that inspects the repository, creates a managed Gitea repository in your OSC workspace, pushes the code there, and then deploys the app.
How to Import
- Go to My Apps.
- Click Import in the top-right corner of the page.
- If you have not yet configured agent credentials, clicking Import opens a setup modal so you can enter your Anthropic or OpenAI API key before proceeding. Once saved, the Import dialog opens automatically.
- Enter the GitHub Repository URL (e.g.
https://github.com/owner/repo). - Optionally provide a GitHub Token if the repository is private.
- If you have credentials configured for both Claude and Codex, select the Runner to use.
- Click Import. OSC creates an agent task and triggers it immediately.
After the import starts, a success banner with a "View progress" link appears. Click it to open the My Agent Tasks page where you can follow the run logs.
What the Import Agent Does
- Inspects the repository to determine the runtime (Node.js, Python, Go, or WASM).
- Creates a managed Gitea repository in your OSC workspace.
- Pushes the source code to that Gitea repository.
- Deploys the app from the Gitea URL (not from GitHub directly) using
create-my-app. - Reports the public URL and Gitea repository link when complete.
After a successful import, all future code changes and Agentic SDLC activity flow through your OSC-managed Gitea repository, not the original GitHub source.
Using MCP Tools
If you have an AI agent connected to OSC via MCP, you can manage agent tasks using natural language.
Setting up credentials
For Claude Runner:
Set up my agent credentials using my Anthropic API key sk-ant-...
For Codex Runner:
Set up my agent credentials using my OpenAI API key sk-... for the codex runner
The setup-agent MCP tool accepts an agentType parameter to target the correct runtime. When you specify an OpenAI key the tool sets agentType to birme-codex-runner automatically. When you specify an Anthropic key it uses birme-claude-runner.
Creating tasks
Create a task that runs with the default Claude Runner:
Create a daily task called "sync-report" that runs every weekday at 9am.
The prompt should be: Review the GitHub issues in my repo and post a summary to Slack.
Use https://github.com/myorg/myrepo as the source URL.
Create a task that runs with Codex Runner:
Create a weekly task called "code-review" that runs every Monday at 8am using the Codex runner.
The prompt should be: Review open pull requests in the repo and add triage comments.
Use https://github.com/myorg/myrepo as the source URL.
Set agentType to birme-codex-runner.
Create a manual (on-demand) task:
Create a manual task called "data-migration" that I can trigger myself.
The prompt should be: Run the database migration script in scripts/migrate.js.
Use https://github.com/myorg/myrepo as the source URL.
Set scheduleType to manual.
Managing tasks
List my agent tasks and show me which ones ran today.
Run my "sync-report" task now.
Delete the agent task called "old-task".
Update the "sync-report" task to run every Monday at 9am instead of every weekday.
To inspect all settings of a specific task before editing it:
Get the full definition of task task-abc123.
The get-agent-task tool returns the complete task definition including prompt, schedule, model, allowed tools, and credential status. This is especially useful before calling update-agent-task so you can read, merge your changes, and write back safely.
Viewing run history and logs
Show me the recent runs for my "sync-report" task.
Get the logs from the latest run of my "daily-report" task.
Show me the logs for run run-abc123 of task task-xyz.
The get-agent-task-logs tool automatically fetches the most recent run if you omit the runId. Logs are truncated to the last 200 lines for very long outputs, with a note indicating how many lines were omitted. If logs have expired the tool returns a friendly message explaining this.
Available MCP tools
| Tool | Description |
|---|---|
setup-agent |
Store agent credentials; accepts agentType (birme-claude-runner or birme-codex-runner) |
create-agent-task |
Create a scheduled agent task; accepts agentType to select the runtime, scheduleType (cron or manual), and optional notificationEmail |
list-agent-tasks |
List all tasks with schedule and last/next run timestamps |
get-agent-task |
Return the full definition of a single task by ID. Use this before update-agent-task to read current settings, merge changes, and write back — enables a safe read-modify-write flow. |
run-agent-task |
Manually trigger an immediate task run |
update-agent-task |
Update fields of an existing task (prompt, schedule, agentType, scheduleType, notificationEmail, etc.) |
delete-agent-task |
Permanently remove a task |
get-agent-task-runs |
List all recorded runs for a task with status and start time |
get-agent-task-logs |
Retrieve log output for a specific run (or the most recent run if runId is omitted) |
Prompt Tips
Write prompts as clear task descriptions. The agent runs non-interactively, so treat the prompt as a complete, self-contained instruction.
Claude Runner prompts:
- "Review open GitHub issues labeled 'bug' in myorg/myrepo and add a comment with a suggested fix approach."
- "Check the health of my OSC services and send a Slack message to #ops if any are unhealthy."
- "Fetch yesterday's analytics data from my Plausible instance and append a row to the Google Sheet at ..."
- "Generate a daily standup summary from my Jira board and post it to #team-standup."
Codex Runner prompts (works best with an AGENTS.md in the repository):
- "Run the daily report task described in AGENTS.md."
- "Review the code in src/ for potential bugs and write a summary to review.md."
- "Run the test suite and report any failures with suggested fixes."
For tasks that interact with code, set Source URL to the relevant repository so the agent can read and modify files in context.
Context Files
Each runtime uses a different conventions file to understand the project:
- Claude Runner reads
CLAUDE.mdat the repository root (or in parent directories). - Codex Runner reads
AGENTS.mdat the repository root.
If you switch a repository between runtimes, add the corresponding context file so the agent has the project background it needs.