# Adding Custom Instructions
Source: https://teamcopilot.ai/docs/adding-custom-instructions

Learn how to add workspace-level custom instructions in TeamCopilot and when to use them.

TeamCopilot supports workspace-level custom instructions through a file called `USER_INSTRUCTIONS.md`.

This file lets you define default instructions that should apply to every new AI session in that workspace.

## Why you would use this

Custom instructions are useful when you want TeamCopilot to consistently follow workspace-wide rules or defaults.

For example, you might use `USER_INSTRUCTIONS.md` to tell the AI:

* information about what your organization does and which industry it is in
* which coding standards your team follows
* which internal conventions matter most
* what environments or systems it should be careful with
* how you want answers formatted by default

This is best for rules that should apply broadly across the workspace, not just to a single skill or workflow.

## How it works

Each time a new chat session is created with the AI, the contents of the `USER_INSTRUCTIONS.md` are injected into the chat automatically.

## Where the file lives

The file must be placed at the root of your TeamCopilot workspace:

```text theme={null}
<workspace>/USER_INSTRUCTIONS.md
```

## How to modify it

TeamCopilot includes a built-in UI for editing workspace-level custom instructions.

To update them:

1. Open the `AI chat` section in TeamCopilot.
2. Click `Modify global AI instructions`.
3. Edit the contents in the editor page that opens.
4. Click `Save`, or use `Cmd+S` / `Ctrl+S`.

Changes are saved immediately to `USER_INSTRUCTIONS.md` at the workspace root.

Only users with the `Engineer` role can modify these instructions. Other users can still see the button, but TeamCopilot will tell them that only engineers can make changes.

If you prefer, you can still edit the file directly on disk at:

```text theme={null}
<workspace>/USER_INSTRUCTIONS.md
```

## Example

Below is an example of the kind of company context you can put into `USER_INSTRUCTIONS.md`:

```md theme={null}
# Company context

You are assisting Acme Logistics.

Acme Logistics provides shipment visibility and route planning software for mid-sized retail and manufacturing companies.

## Business

- Industry: logistics technology / supply chain software
- Region: primarily North America and Western Europe
- Customers: operations teams, supply chain managers, and logistics directors at mid-market companies
- Product: SaaS platform for tracking shipments, planning routes, and monitoring carrier performance

## Important context

- Our customers care most about reliability, speed, and cost control.
- We operate in a B2B environment, so responses should be professional and practical.
- Avoid overly technical explanations unless the user is clearly an engineering user.
- When writing customer-facing content, prefer clear operational language over marketing buzzwords.

## Response preferences

- When relevant, frame answers in terms of customer impact.
- If discussing product ideas, prioritize operational efficiency and reporting.
- If discussing bugs or incidents, clearly explain business impact, affected customers, and urgency.
```


# Add a user and setup authentication
Source: https://teamcopilot.ai/docs/adding-users

See how to configure auth for teammates

## Adding a user

Before anyone can sign in, they need to be added to your instance of TeamCopilot using an admin command: `npx teamcopilot create-user` from the same directory where you initialized TeamCopilot.

This command will ask you for the user's:

* Email
* Name
* Role (Engineer or User)
* Temporary password

The temporary password you set here can be used by the user to login, and immediately after that, TeamCopilot will ask the user to set a new password.

## About User roles

There are two roles:

* User
* Engineer

Engineers can do everything that users can, but they can also approve custom skills and workflows created by anyone in the team.

## Other admin commands

The CLI also includes:

* `npx teamcopilot change-user-role`
* `npx teamcopilot delete-user`
* `npx teamcopilot reset-password`
* `npx teamcopilot rotate-jwt-secret`

Use `change-user-role` to promote a user to Engineer or demote them back to User. Use `rotate-jwt-secret` only when you want to force everyone to sign in again.


# CEO and Executive Team
Source: https://teamcopilot.ai/docs/examples/ceo-and-executive-team

See how executives can use TeamCopilot with skills and workflows for summaries, updates, and recurring leadership reports.

Executives usually do not need low-level automation. They benefit most from skills that help synthesize information and workflows that package recurring reports.

## Example setup

* A **skill** for board-update formatting
* A **skill** for executive summary writing
* A **workflow** that gathers metrics from internal systems and produces a leadership report

## Example requests

* "Summarize this week's product and revenue updates for an executive audience."
* "Turn these notes into a board-style update."
* "Run the weekly leadership-report workflow."

## Why this works

The skills help the AI communicate at the right level for leadership. The workflow ensures the underlying numbers and inputs are gathered consistently.

This setup usually pairs well with:

* [Token usage analytics](/docs/workflows-and-skills/token-usage-analytics)
* [Chat and sessions](/docs/workflows-and-skills/chat-and-sessions)
* [Run history](/docs/workflows-and-skills/run-history)

## Example `SKILL.md`

Below is an example executive communication skill for turning raw updates into leadership-ready summaries.

```md theme={null}
---
name: executive-weekly-summary
description: Turn detailed team updates into concise executive summaries for leadership and board-level readers.
---

# Executive Weekly Summary

Use this skill when the user wants a leadership-ready summary of product, revenue, operations, hiring, or company updates.

## Writing principles

- Lead with the most important business outcomes.
- Be concise and easy to scan.
- Separate facts from risks and decisions.
- Avoid technical detail unless it changes business impact.
- Prefer clear language over internal jargon.

## Recommended structure

1. Top-line summary
2. Wins
3. Risks
4. Decisions needed
5. Metrics or trends

## Output format

When summarizing:

1. Start with a short executive summary.
2. Use flat bullets for key points.
3. Call out risks and asks clearly.
4. Keep the tone crisp and neutral.

## Constraints

- Do not invent metrics or confidence.
- If a data point is unclear, mark it as uncertain.
- If the source material is too detailed, compress aggressively.
```

## Example workflow `run.py`

Below is an example workflow that reads KPI data from a JSON file and prints a simple weekly leadership summary.

```python theme={null}
import argparse
import json
from pathlib import Path


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True, help="Path to weekly KPI JSON file")
    return parser.parse_args()


def load_data(path: Path):
    with path.open("r", encoding="utf-8") as handle:
        return json.load(handle)


def fmt_change(value):
    sign = "+" if value >= 0 else ""
    return f"{sign}{value:.1f}%"


def main():
    args = parse_args()
    path = Path(args.input)

    if not path.exists():
        raise SystemExit(f"Input file not found: {path}")

    data = load_data(path)
    revenue = float(data.get("revenue", 0))
    revenue_change = float(data.get("revenue_change_pct", 0))
    active_customers = int(data.get("active_customers", 0))
    customer_change = float(data.get("customer_change_pct", 0))
    churn_risk = data.get("churn_risk", "unknown")
    key_note = data.get("key_note", "No additional note provided.")

    print("Weekly Leadership Report")
    print("========================")
    print(f"Revenue: ${revenue:,.2f} ({fmt_change(revenue_change)} week-over-week)")
    print(f"Active customers: {active_customers} ({fmt_change(customer_change)} week-over-week)")
    print(f"Churn risk: {churn_risk}")
    print()
    print("Executive note:")
    print(key_note)


if __name__ == "__main__":
    main()
```


# Developers
Source: https://teamcopilot.ai/docs/examples/developers

See how developers can use TeamCopilot with skills and workflows for code review, release work, and engineering operations.

Developers often benefit from TeamCopilot across code review, release operations, debugging, and engineering workflows.

## Example setup

* A **skill** for code review standards
* A **skill** for release procedures
* A **workflow** for deployment, changelog generation, or environment checks

## Example requests

* "Review this PR using our backend review standards."
* "Use our release skill to validate whether this version is ready."
* "Run the staging deploy workflow."

## Why this works

The skills capture engineering judgment and team conventions. The workflows handle the parts that should be automated and repeatable.

This setup usually pairs well with:

* [Permissions](/docs/workflows-and-skills/permissions)
* [Approval review](/docs/workflows-and-skills/approvals-and-review)
* [Run history](/docs/workflows-and-skills/run-history)

## Example `SKILL.md`

Below is an example developer skill for code review.

```md theme={null}
---
name: backend-code-review
description: Review backend code changes for correctness, regressions, maintainability, and operational risk.
---

# Backend Code Review

Use this skill when the user asks for a code review on backend or infrastructure-related changes.

## Review priorities

Focus on:

- correctness
- regressions
- missing validation
- error handling
- permission and security risks
- missing tests

## How to review

1. Understand the purpose of the change.
2. Identify behavior changes, not just style issues.
3. Check whether the implementation matches the intended contract.
4. Look for failure modes and edge cases.
5. Check whether tests cover the important paths.

## Output format

When performing review:

1. Start with findings, ordered by severity.
2. Include file references when possible.
3. Keep summaries brief.
4. If no major issues are found, say that explicitly and mention residual risks.

## Constraints

- Do not focus on formatting unless it affects readability or correctness.
- Prefer actionable findings over generic commentary.
- Call out missing tests when behavior changes are not covered.
```

## Example workflow `run.py`

Below is an example developer workflow that generates a simple changelog from git commits between two refs.

```python theme={null}
import argparse
import subprocess
import sys


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--base_ref", required=True, help="Older git ref")
    parser.add_argument("--head_ref", required=True, help="Newer git ref")
    return parser.parse_args()


def run_git_log(base_ref: str, head_ref: str):
    cmd = [
        "git",
        "log",
        "--pretty=format:%h|%an|%s",
        f"{base_ref}..{head_ref}",
    ]
    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip() or "git log failed")
    return [line for line in result.stdout.splitlines() if line.strip()]


def main():
    args = parse_args()

    try:
        entries = run_git_log(args.base_ref, args.head_ref)
    except Exception as exc:  # noqa: BLE001
        print(f"Failed to build changelog: {exc}", file=sys.stderr)
        sys.exit(1)

    print("Release Changelog")
    print("=================")
    print(f"Range: {args.base_ref}..{args.head_ref}")
    print()

    if not entries:
        print("No commits found in the selected range.")
        return

    for entry in entries:
        sha, author, subject = entry.split("|", 2)
        print(f"- {subject} ({sha}, {author})")


if __name__ == "__main__":
    main()
```


# Real-Life Examples
Source: https://teamcopilot.ai/docs/examples/index

Explore practical examples of how different teams can use TeamCopilot with skills and workflows.

TeamCopilot becomes most valuable when it is mapped to how each team already works.

This section shows practical examples for different roles and departments. Each example illustrates:

* the kinds of skills that team might use
* the kinds of workflows that team might run
* the kinds of prompts people might actually type into TeamCopilot

Across all of these examples, the pattern is the same:

* use **skills** to capture how a team thinks, reviews, writes, or decides
* use **workflows** to automate what a team needs to run repeatedly
* use **approval review** before broad rollout
* use **permissions** to control who can use each resource
* use **secrets** instead of hardcoding credentials
* use **cronjobs** for recurring work

Choose an example based on the team you are implementing TeamCopilot for:

* [Marketing team](/docs/examples/marketing-team)
* [QA team](/docs/examples/qa-team)
* [Developers](/docs/examples/developers)
* [CEO and executive team](/docs/examples/ceo-and-executive-team)

For the underlying platform behavior, also read:

* [Chat and sessions](/docs/workflows-and-skills/chat-and-sessions)
* [Approval review](/docs/workflows-and-skills/approvals-and-review)
* [Secret management](/docs/workflows-and-skills/secret-management)
* [Cronjobs](/docs/workflows-and-skills/cronjobs)


# Marketing Team
Source: https://teamcopilot.ai/docs/examples/marketing-team

See how a marketing team can use TeamCopilot with skills and workflows for campaigns, content, and reporting.

A marketing team might use TeamCopilot for campaign preparation, content operations, and reporting.

## Example setup

* A **skill** for brand voice and messaging rules
* A **skill** for launch checklist and campaign review standards
* A **workflow** that pulls campaign metrics and generates a weekly report

## Example requests

* "Draft a launch email using our brand voice."
* "Review this landing page copy using our messaging guidelines."
* "Run the weekly marketing-report workflow for the last 7 days."

## Why this works

The skills help the AI write and review content the way the marketing team expects. The workflow handles the repeatable reporting work.

This setup usually pairs well with:

* [Skills concepts](/docs/workflows-and-skills/concepts)
* [Approval review](/docs/workflows-and-skills/approvals-and-review)
* [Secret management](/docs/workflows-and-skills/secret-management)
* [Cronjobs](/docs/workflows-and-skills/cronjobs)

## Example `SKILL.md`

Below is an example marketing skill for reviewing campaign copy against a team's brand voice.

```md theme={null}
---
name: marketing-brand-voice
description: Review and improve marketing copy so it matches our brand voice, audience, and campaign positioning.
---

# Marketing Brand Voice

Use this skill when the user wants help drafting, reviewing, or refining marketing copy.

## When to use

Use this skill for:

- email campaigns
- landing page copy
- launch messaging
- ad copy
- product announcements

Do not use this skill for legal review, pricing approval, or final publishing decisions.

## Brand voice rules

- Write in a clear, confident, direct tone.
- Avoid buzzwords and vague claims.
- Prefer concrete value over hype.
- Keep language simple and easy to scan.
- Focus on customer outcomes, not internal features alone.

## Review checklist

When reviewing copy:

1. Identify the intended audience.
2. Check whether the main message is clear in the first few lines.
3. Remove fluff, repetition, and generic phrases.
4. Rewrite lines that sound off-brand or too technical.
5. Make sure the call to action is specific.

## Output format

When the user asks for review:

1. Summarize what is working.
2. List the biggest issues.
3. Provide an improved version.
4. Explain major edits briefly.

## Constraints

- Do not invent customer results or metrics.
- Do not make legal, compliance, or pricing claims unless the user explicitly provides them.
- If brand guidance conflicts with the user's request, point out the conflict clearly.
```

## Example workflow `run.py`

Below is an example workflow that reads weekly marketing metrics from a CSV file and prints a simple report.

```python theme={null}
import argparse
import csv
from datetime import datetime, timedelta
from pathlib import Path


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--csv_path", required=True, help="Path to campaign metrics CSV file")
    parser.add_argument("--days", type=int, default=7, help="How many recent days to include")
    return parser.parse_args()


def load_rows(csv_path: Path):
    with csv_path.open("r", encoding="utf-8") as handle:
        reader = csv.DictReader(handle)
        return list(reader)


def main():
    args = parse_args()
    csv_path = Path(args.csv_path)

    if not csv_path.exists():
        raise SystemExit(f"Metrics file not found: {csv_path}")

    rows = load_rows(csv_path)
    cutoff = datetime.utcnow().date() - timedelta(days=args.days)

    filtered = []
    for row in rows:
        row_date = datetime.strptime(row["date"], "%Y-%m-%d").date()
        if row_date >= cutoff:
            filtered.append(row)

    if not filtered:
        print("No campaign data found for the selected date range.")
        return

    total_impressions = sum(int(row.get("impressions", 0) or 0) for row in filtered)
    total_clicks = sum(int(row.get("clicks", 0) or 0) for row in filtered)
    total_signups = sum(int(row.get("signups", 0) or 0) for row in filtered)
    total_spend = sum(float(row.get("spend", 0) or 0) for row in filtered)

    ctr = (total_clicks / total_impressions * 100) if total_impressions else 0.0
    signup_rate = (total_signups / total_clicks * 100) if total_clicks else 0.0
    cost_per_signup = (total_spend / total_signups) if total_signups else 0.0

    print("Weekly Marketing Report")
    print("=======================")
    print(f"Date range: last {args.days} days")
    print(f"Campaign rows analyzed: {len(filtered)}")
    print(f"Impressions: {total_impressions}")
    print(f"Clicks: {total_clicks}")
    print(f"CTR: {ctr:.2f}%")
    print(f"Signups: {total_signups}")
    print(f"Signup rate: {signup_rate:.2f}%")
    print(f"Spend: ${total_spend:.2f}")
    print(f"Cost per signup: ${cost_per_signup:.2f}")


if __name__ == "__main__":
    main()
```


# QA Team
Source: https://teamcopilot.ai/docs/examples/qa-team

See how a QA team can use TeamCopilot with skills and workflows for bug triage, test cases, and validation.

A QA team might use TeamCopilot for bug triage, test-case generation, and recurring validation tasks.

## Example setup

* A **skill** for bug triage rules and severity definitions
* A **skill** for how to write reproducible test cases
* A **workflow** that runs a recurring validation or smoke-check routine

## Example requests

* "Classify this bug using our severity framework."
* "Turn this issue into a reproducible QA test case."
* "Run the staging smoke-test workflow."

## Why this works

The skills standardize how defects are described and prioritized. The workflow gives QA a reliable way to run the same checks repeatedly.

This setup usually pairs well with:

* [Skills concepts](/docs/workflows-and-skills/concepts)
* [Permissions](/docs/workflows-and-skills/permissions)
* [Approval review](/docs/workflows-and-skills/approvals-and-review)
* [Run history](/docs/workflows-and-skills/run-history)

## Example `SKILL.md`

Below is an example QA skill for triaging incoming bugs consistently.

```md theme={null}
---
name: qa-bug-triage
description: Classify bugs, identify missing reproduction details, and recommend next QA actions.
---

# QA Bug Triage

Use this skill when the user shares a defect report, test failure, or issue that needs triage.

## Triage goals

- determine severity
- identify missing reproduction details
- separate product issues from environment issues
- recommend next steps for QA and engineering

## Severity framework

- Critical: production outage, data loss, security issue, or core workflow blocked for many users
- High: major functionality broken with no reasonable workaround
- Medium: meaningful issue with workaround available or limited scope
- Low: cosmetic issue, edge case, or low-impact bug

## Required checks

1. Confirm the affected environment.
2. Confirm expected behavior and actual behavior.
3. Check whether reproduction steps are complete.
4. Note whether the issue is consistent or intermittent.
5. Identify any logs, screenshots, or payloads still needed.

## Output format

When triaging a bug:

1. Give the proposed severity.
2. Explain why.
3. List missing information.
4. Rewrite the bug report in a clearer format.
5. Suggest next QA or engineering actions.

## Constraints

- Do not claim root cause unless evidence supports it.
- If reproduction details are weak, say so explicitly.
- Distinguish clearly between observed facts and hypotheses.
```

## Example workflow `run.py`

Below is an example smoke-check workflow that reads expected endpoints from a JSON file and validates that they respond successfully.

```python theme={null}
import argparse
import json
import sys
from pathlib import Path
from urllib import request, error


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--config", required=True, help="Path to smoke test config JSON")
    return parser.parse_args()


def load_config(config_path: Path):
    with config_path.open("r", encoding="utf-8") as handle:
        return json.load(handle)


def check_url(url: str, timeout: int):
    req = request.Request(url, method="GET")
    try:
        with request.urlopen(req, timeout=timeout) as response:
            return response.status, None
    except error.HTTPError as exc:
        return exc.code, str(exc)
    except Exception as exc:  # noqa: BLE001
        return None, str(exc)


def main():
    args = parse_args()
    config_path = Path(args.config)

    if not config_path.exists():
        raise SystemExit(f"Config file not found: {config_path}")

    config = load_config(config_path)
    timeout = int(config.get("timeout_seconds", 10))
    checks = config.get("checks", [])

    if not checks:
        print("No checks configured.")
        return

    failures = []
    print("Smoke Test Results")
    print("==================")

    for check in checks:
        name = check["name"]
        url = check["url"]
        status, err = check_url(url, timeout)

        if status and 200 <= status < 400:
            print(f"[PASS] {name}: {url} -> {status}")
        else:
            print(f"[FAIL] {name}: {url} -> {status or 'error'}")
            if err:
                print(f"       {err}")
            failures.append(name)

    print()
    print(f"Total checks: {len(checks)}")
    print(f"Failures: {len(failures)}")

    if failures:
        sys.exit(1)


if __name__ == "__main__":
    main()
```


# Installation
Source: https://teamcopilot.ai/docs/index

Learn what TeamCopilot is and how to install and set it up for your team.

TeamCopilot is a shared AI agent for teams. Instead of every person maintaining their own local agent setup, your team configures one shared environment that everyone can use through the same agent and web UI.

It is designed for teams that want:

* One shared agent setup instead of separate personal setups
* Shared custom skills and tools that can be reused across the team
* Permission controls for sensitive skills and tools
* Approval workflows before new skills or tools become available
* A self-hosted deployment model so chats, secrets, and data stay on your infrastructure
* Access from a web UI, including when you are away from your work machine

The docs in this site cover the main operating areas:

* setup and model authentication
* skills and workflows
* approvals and permissions
* secrets
* chat sessions and diffs
* cronjobs
* run history
* usage analytics

## Installation and setup

The quickest way to get started is with the npm-based setup from the TeamCopilot repository.

### Prerequisites

* Node.js 20+
* npm
* Python 3.10+

### 1. Initialize TeamCopilot

Run the initializer in the folder you want TeamCopilot to use:

```bash theme={null}
npx teamcopilot init
```

This writes or updates a local `.env` file in the current directory. By default, `WORKSPACE_DIR` is set to the current directory as an absolute path.

If you want to provide values up front, you can pass them during initialization:

```bash theme={null}
npx teamcopilot init \
  --workspace-dir /absolute/path/to/workspace \
  --teamcopilot-port 5124 \
  --opencode-port 4096 \
  --opencode-model openai/gpt-5.4-mini
```

### 2. Start the server

```bash theme={null}
npx teamcopilot start
```

After the server starts, open `http://localhost:5124`.

### Environment variables created by the `init` command

* `WORKSPACE_DIR`: Directory where workflows, user data and skills are stored
* `TEAMCOPILOT_HOST`: Server host, default `0.0.0.0`
* `TEAMCOPILOT_PORT`: Server port, default `5124`
* `OPENCODE_PORT`: Internal OpenCode server port, default `4096`
* `OPENCODE_MODEL`: Model used by OpenCode

If you want dashboard-generated workflow API curl examples to point at the right public host, also set `EXTERNAL_HOST` to the externally reachable base URL for the TeamCopilot instance.

## What to read next

* [Add users](/docs/adding-users)
* [Set up model access](/docs/setting-up-model)
* [Custom instructions](/docs/adding-custom-instructions)
* [Workflows and skills concepts](/docs/workflows-and-skills/concepts)
* [Chat and sessions](/docs/workflows-and-skills/chat-and-sessions)
* [Secrets](/docs/workflows-and-skills/secret-management)


# Setting up OpenAI / Gemini / Claude access
Source: https://teamcopilot.ai/docs/setting-up-model

See how to enable OpenAI, Azure OpenAI, Gemini, or Claude access

## Setting up with GPT / OpenAI

Once you have created your first user and signed in, the dashboard will ask you to give access to an OpenAI account via:

* Adding an API key: You can get an OpenAI key via the OpenAI developer console.
* Signing into a subscription account: If you pick this method, OpenAI will give you an error during sign in to enable the device flow login method. You need to follow the instructions on that popup and then try signing into TeamCopilot again.

<img alt="OpenAI setup" />

## Setting up with Azure OpenAI

Azure OpenAI is configured by the TeamCopilot service administrator through environment variables instead of the in-app auth flow.

To use Azure OpenAI:

* Stop the running TeamCopilot instance
* In the `.env` file created by TeamCopilot (in your workspace directory), set the Azure credentials and deployment details:

```bash theme={null}
AZURE_API_KEY=<your-azure-openai-api-key>
AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
OPENCODE_MODEL=azure-openai/<your-deployment-name>
```

* Replace `<your-resource>` with your Azure OpenAI resource name
* Replace `<your-deployment-name>` with the Azure deployment name you created in Azure OpenAI
* Restart the server using `npx teamcopilot start`

After the server restarts, TeamCopilot will use the Azure OpenAI deployment configured in those environment variables. In the UI this provider is shown as managed by the administrator and is read-only for regular users.

## What the UI does

When the app detects missing credentials, it redirects users to the OpenCode auth setup screen instead of the normal chat UI.

If the provider is managed by environment variables, users can view the configured provider but they cannot edit those values from the browser.

## Setting up with Gemini

Gemini is configured by the TeamCopilot service administrator through environment variables instead of the in-app auth flow.

To use Gemini:

* Stop the running TeamCopilot instance
* In the `.env` file created by TeamCopilot (in your workspace directory), set the Vertex project, credentials, location, and model details:

```bash theme={null}
GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
VERTEX_LOCATION=global
OPENCODE_MODEL=google-vertex/<your-model-id>
```

* Replace `<your-gcp-project-id>` with your Google Cloud project ID
* Point `GOOGLE_APPLICATION_CREDENTIALS` to a readable Google Cloud service account JSON key file
* Set `VERTEX_LOCATION` to a Vertex region or endpoint such as `global` or `us-central1`
* Replace `<your-model-id>` with the Gemini model id you want to use
* If you are using a provider-specific OpenCode Vertex backend, keep that provider prefix in `OPENCODE_MODEL`
* Restart the server using `npx teamcopilot start`

After the server restarts, TeamCopilot will use the Gemini model configured in those environment variables. In the UI this provider is shown as managed by the administrator and is read-only for regular users.

## Setting up with Claude / Anthropic

### Using Anthropic API key

If instead, you want to use Claude:

* Stop the running TeamCopilot instance
* In the `.env` file created by TeamCopilot (in your workspace directory), modify the `OPENCODE_MODEL` to be `OPENCODE_MODEL=anthropic/claude-opus-4-6`
* Restart the server using `npx teamcopilot start`
* Now when you visit the dashboard, it will ask you to give access to your Claude account.

With Anthropic, the only available method is via an API key.

<img alt="Claude setup" />

### Using Google Vertex

If you want to use Anthropic models through Google Vertex, configure the service administrator environment variables and set the provider-specific model id:

```bash theme={null}
GOOGLE_CLOUD_PROJECT=<your-gcp-project-id>
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
VERTEX_LOCATION=global
OPENCODE_MODEL=google-vertex-anthropic/<your-model-id>
```

* `google-vertex-anthropic` is the provider prefix for Anthropic models on Google Vertex
* Use the Anthropic model id you want to run through Vertex in `OPENCODE_MODEL`
* Keep the Google Cloud project, credentials, and location variables configured for the workspace

## General recommendations

* We recommend using the API key method since this will ensure no interruptions during workflows as long as you have credits in your account (as opposed to subscription which can have very heavy rate limits, especially if many people are using this tool). This is especially true for Claude since their terms of use states that their subscription account should only be used when using Claude code.
* Use any model that is equal to or more capable than:
  * For OpenAI: Codex 5.3+ or GPT 5.4+
  * For Azure OpenAI: a deployment backed by Codex 5.3+ or GPT 5.4+
  * For Gemini: a model that matches your team's needs and is supported by the configured Vertex provider
  * For Anthropic: Claude Opus 4.6+

## Changing models after initial setup

If you want to change the model or model provider used after the initial setup, you can do so by changing the `OPENCODE_MODEL` value in the `.env` file in the workspace directory and then restarting the TeamCopilot service.

In addition to this, if you ever want to change the auth method (switch to API method from subscription method or vice versa):

* Login as an Engineer into TeamCopilot
* Navigate to the AI chat section
* Click on the "Reconfigure Opencode Auth" button
* Follow the instructions to setup new auth.

<img alt="Reconfigure Opencode Auth button in the AI chat section" />


# Admin CLI
Source: https://teamcopilot.ai/docs/workflows-and-skills/admin-cli

Reference for the TeamCopilot admin commands used to manage users and workspace secrets.

TeamCopilot includes a small admin CLI for workspace maintenance.

## User management commands

* `npx teamcopilot create-user`
* `npx teamcopilot change-user-role`
* `npx teamcopilot delete-user`
* `npx teamcopilot reset-password`
* `npx teamcopilot rotate-jwt-secret`

## What each command is for

* `create-user`: add a teammate before they can sign in
* `change-user-role`: promote or demote a user between `User` and `Engineer`
* `delete-user`: remove a user account from the workspace
* `reset-password`: reset a user's login password
* `rotate-jwt-secret`: invalidate existing sessions and force everyone to log in again

## Operational note

Run these commands from the same workspace directory that TeamCopilot uses.

If the environment file is missing or incomplete, initialize the workspace first with `npx teamcopilot init`.


# Approval Review
Source: https://teamcopilot.ai/docs/workflows-and-skills/approvals-and-review

Learn how TeamCopilot approval review works for skills and workflows, including snapshots, diffs, and restore flows.

TeamCopilot uses approval review to decide when a skill or workflow version is trusted enough for regular use.

```mermaid theme={null}
flowchart LR
    A[Edit skill or workflow] --> B[Build current snapshot]
    B --> C{Matches approved snapshot?}
    C -->|Yes| D[Resource remains approved]
    C -->|No| E[Show approval diff]
    E --> F[Engineer reviews files]
    F --> G{Approve or restore?}
    G -->|Approve| H[Store new approved snapshot]
    G -->|Restore| I[Revert to last approved snapshot]
```

## What approval means

Approval is tied to the current filesystem snapshot of the resource.

When a resource is approved, TeamCopilot records:

* the approved snapshot hash
* the number of files in the approved version
* who approved it
* when it was approved

If the resource changes after approval, the current code is no longer considered approved until it is reviewed again.

## Who can approve

Only engineers can review and approve the current version of a skill or workflow.

This is the control point that separates authorship from trust. A user can create or edit a resource, but approval is still a deliberate step.

## What the review screen shows

The approval review page is meant to answer:

* what changed
* which files were added, modified, or deleted
* whether there are binary files
* whether anything was ignored in the diff
* whether the current version matches the approved snapshot

For many resources, the diff is enough to review in text. If a resource has a large file tree or binary-heavy changes, a screenshot may help, but it is not required for the general case.

## What happens after approval

Once a resource is approved:

* the current snapshot is stored as the trusted version
* permissions can be managed normally
* approved content can be used by the agent runtime

If the resource changes later, TeamCopilot treats it as pending again until reviewed.

```mermaid theme={null}
sequenceDiagram
    participant E as Engineer
    participant UI as Approval review page
    participant B as Backend
    participant S as Snapshot store

    E->>UI: Open review page
    UI->>B: Request current and approved snapshots
    B->>S: Load last approved snapshot
    B-->>UI: Diff + approval state
    E->>UI: Approve or restore
    UI->>B: Submit action
    B->>S: Update approved snapshot or restore files
```

## Restore to approved version

The review flow can restore a resource back to the last approved snapshot.

This is useful when:

* a change was accidental
* a review failed and you want to revert quickly
* the approved version is still the desired baseline

## Relationship to permissions

Permissions and approval are separate:

* approval says whether the current version is trusted
* permissions say who can view or run it

You generally want both:

* approve the resource before wider use
* then decide whether access should be restricted or open to everyone


# AI Chat and Sessions
Source: https://teamcopilot.ai/docs/workflows-and-skills/chat-and-sessions

Learn how TeamCopilot chat sessions work, how to read diffs, and how session-level controls affect permissions and approvals.

TeamCopilot's AI chat is the main entry point for day-to-day use. From the chat tab, users can create sessions, continue older sessions, inspect file diffs, answer permission prompts, and interact with cronjob handoff sessions.

## What a chat session is

A chat session is a persistent conversation with the agent. TeamCopilot stores:

* the messages in the session
* the session title and timestamps
* pending tool and permission requests
* tracked file changes for the session
* usage data for cost and token analytics

Sessions can be reopened later from the history list or via deep links.

## Main chat behaviors

In the UI, users can:

* start a new session
* continue an existing session
* attach files from the workspace
* review tracked file diffs
* respond to permission requests
* answer agent questions when the assistant is waiting on input
* delete a session when it is no longer needed

The chat UI also supports read-state tracking so attention-needed sessions can be marked as seen.

## Deep links

The app supports session deep links through query parameters:

* `/?tab=ai&session=<session_id>` opens a specific session
* `/?tab=ai&newChat=1` opens a fresh session flow
* `/?tab=ai&draft=<text>` pre-fills a draft message

These links are useful for sending someone directly to a specific conversation state.

## File attachments

You can attach workspace files in chat messages.

Rules:

* file paths must stay inside the workspace
* paths are normalized before use
* the agent receives a file URL only after the backend validates the path

This prevents the chat UI from being used to reference files outside the shared workspace.

## Permission requests

When the agent wants to do something sensitive, TeamCopilot may create a permission request.

Users can respond with:

* `once`
* `always`
* `reject`

Permission prompts are session-scoped, and the UI removes them once answered.

## File diffs

TeamCopilot tracks file changes made during a session and exposes a diff view in the chat UI.

The diff panel is useful for:

* reviewing what the agent changed
* checking whether an edit matched the user's intent
* auditing tool-driven file changes after the session

Diffs are built from the tracked session file baseline and the current workspace state.

## Session states

Sessions can show different states in the UI, including:

* active
* pending input
* attention needed
* read
* deleted

The backend also normalizes stale tool states so interrupted or incomplete runs do not remain stuck in a misleading state.

## Cronjob chat handoff

Some cronjob runs use a chat session as the execution surface.

In those cases, TeamCopilot can:

* pause a cronjob run when it needs user attention
* resume the run later from the chat UI
* interrupt or terminate the run from the session controls

This is important for prompt-based cronjobs where the agent may need to ask for clarification before it can continue.

## Workflow sessions and hidden tool prompts

Some workflow and cronjob flows create hidden session state while they run. The UI only reveals those details when the run is surfaced in the chat view or run detail page.

That keeps the normal chat view focused on the user-facing interaction while still preserving auditability in the backend.


# Understanding Workflows & Skills
Source: https://teamcopilot.ai/docs/workflows-and-skills/concepts

Learn the difference between skills and workflows in TeamCopilot, how they work together, and when your organization should use each one.

TeamCopilot gives your organization two main ways to extend what the AI can do: **skills** and **workflows**.

* A **skill** tells the AI *how to think and operate* for a certain kind of task.
* A **workflow** tells the system *what code to run* for a certain kind of task.

Skills are best for reusable guidance and decision-making. Workflows are best for repeatable automation.

## What is a skill?

A skill is a set of instructions written in natural language, in a `SKILL.md` file. It acts as a reusable operating guide for the AI.

* It explains what the task is.
* It explains how the AI should approach that task.
* It can define rules, constraints, checks, and best practices.
* It can point the AI to relevant files, scripts, or resources.

Skills are especially useful when success depends on judgment, process, context, or organizational standards.

For example, a skill can tell the AI:

* how your team handles incident response
* how to prepare a customer-ready RCA
* how to validate a release before shipping
* what internal rules must be followed when making infrastructure changes

A skill does **not** need to contain executable logic. Its job is to shape the AI's behavior.

## What is a workflow?

A workflow is a runnable automation package, built around Python code. In TeamCopilot, it usually includes:

* a `workflow.json` file that describes the workflow
* a `run.py` entrypoint that performs the task
* optional inputs
* a runtime timeout
* an isolated Python environment and any supporting files the code needs

Workflows are useful when you want something to be:

* repeatable
* deterministic
* auditable
* parameterized with inputs
* runnable on demand without relying on the AI to re-create the logic every time

For example, a workflow can:

* generate a report from a database
* sync data between systems
* provision a standard resource
* run a scheduled or manual operations task
* perform a multi-step API integration reliably

## The core difference

Here is the practical difference:

| Topic           | Skill                                                      | Workflow                                                        |
| --------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| Primary purpose | Teach the AI how to handle a class of tasks                | Execute a concrete task in code                                 |
| Format          | Natural-language instructions in `SKILL.md`                | Python-based runnable package with `workflow.json` and `run.py` |
| Best for        | Judgment, standards, reasoning, process guidance           | Repeatable automation, integrations, deterministic steps        |
| Inputs          | Usually conversational context from the user and workspace | Explicit structured inputs defined in the workflow manifest     |
| Output style    | Varies based on the AI's response                          | Output from a scripted run                                      |
| Execution model | The AI reads and follows it                                | TeamCopilot runs the code                                       |
| Reusability     | Reusable playbook for similar tasks                        | Reusable automation for the same operation                      |

## How skills and workflows work together

A common pattern looks like this:

1. A **skill** tells the AI how to approach a task.
2. The skill explains when a **workflow** should be used.
3. The workflow performs the actual scripted execution.
4. The AI then interprets or communicates the result back to the user.

For example:

* A deployment skill can explain your release checklist, required validations, and rollback rules.
* A deployment workflow can perform the actual deployment steps against your systems.

In that setup, the skill gives the AI the playbook, and the workflow gives it the tool.

## When to use a skill

Use a skill when the main value is helping the AI behave correctly.

Choose a skill when:

* the task is mostly about instructions, judgment, or process
* you want the AI to follow your team's standards
* the steps may vary depending on context
* the task involves reviewing, reasoning, summarizing, planning, or decision support
* you want to guide the AI toward the right files, tools, or checks

## When to use a workflow

Use a workflow when the main value is reliable execution.

Choose a workflow when:

* the same task should run the same way each time
* you need code to call APIs, read systems, or transform data
* the task benefits from structured inputs and validation
* you want a task to run standalone, without the AI improvising the implementation
* you need a concrete execution record for an operation

## When to use both

Use both when the task needs AI judgment plus reliable automation.

* put the human-readable guidance in a **skill**
* put the repeatable code in a **workflow**

## A simple rule of thumb

Ask this question:

> Is this mainly something I want the AI to understand, or mainly something I want the system to run?

If the answer is **understand**, start with a **skill**.

If the answer is **run**, start with a **workflow**.

If the answer is **both**, use both.

## Recommended approach for most teams

When implementing TeamCopilot for your organization:

* start with **skills** for team-specific knowledge, rules, and ways of working
* add **workflows** for tasks that need reliability, external system access, or structured execution
* combine them for important operational flows where both guidance and automation matter

This gives you a practical operating model: **skills** capture how your team works, and **workflows** capture what your systems should do.


# Creating a Skill
Source: https://teamcopilot.ai/docs/workflows-and-skills/creating-a-skill

Learn how to create a skill in TeamCopilot, what files it starts with, and how to write instructions the AI can reliably follow.

A skill is the right choice when you want to teach the AI how your team handles a task.

In TeamCopilot, you can create a skill in two ways:

* manually from the **Skills** tab
* by asking the **AI Assistant** to create one for you

In both cases, the skill is stored as instruction files in your workspace.

## Before you create one

Create a skill when:

* you want reusable instructions for the AI
* the task depends on judgment, policy, or process
* you want the AI to follow your team's way of working

If the task needs code to run against APIs, databases, or external systems, create a workflow instead.

## Two ways to create a skill

### Create a skill manually

1. Open TeamCopilot.
2. Go to the **Skills** tab.
3. Click **Create Skill**.
4. Enter a skill name.
5. Open the new skill in the editor.
6. Edit the `SKILL.md` file.
7. Save your changes.
8. Have an engineer approve the skill before your team starts using it.

When you create a skill, TeamCopilot normalizes the name into a lowercase slug. The name and slug are treated as the same value.

### Create a skill with AI

1. Open TeamCopilot.
2. Go to the **AI Assistant**.
3. Ask the assistant to create a skill for a specific task or process.
4. Describe what the skill should do, when it should be used, and any rules it must follow.
5. Review the generated skill in the **Skills** tab.
6. Refine the `SKILL.md` instructions as needed.
7. Have an engineer approve the skill before your team starts using it.

This is useful when you want a fast first draft and prefer refining instructions instead of writing them from scratch.

## What gets created

Each skill lives in:

```text theme={null}
.agents/skills/<slug>/
```

The main file is:

```text theme={null}
SKILL.md
```

That file is the source of truth for the skill.

## Import existing skills

You do not always need to create a skill from scratch. You can also import existing skills into TeamCopilot.

One practical option is to use the [`skills`](https://www.npmjs.com/package/skills) CLI on the machine where the TeamCopilot service is running.

### How to import skills

1. Access the machine where TeamCopilot is running.
2. Navigate to your TeamCopilot workspace directory.
3. Run an `npx skills add ...` command from that workspace.
4. Confirm the install target if prompted.
5. Verify that the imported skills appear under `.agents/skills/`.
6. Open TeamCopilot and go to the **Skills** tab.
7. Have an engineer review and approve the imported skills.
8. After approval, update permissions so the right people or the whole team can use them.

Because the CLI installs project-scoped skills into the workspace, imported skills end up in TeamCopilot's `.agents/skills/` folder, where TeamCopilot can discover them.

### Example commands

List the skills available in a repository before installing:

```bash theme={null}
npx skills add vercel-labs/agent-skills --list
```

Install a specific skill into the current workspace:

```bash theme={null}
npx skills add vercel-labs/agent-skills --skill frontend-design -a opencode
```

Install all skills from a repository into the current workspace:

```bash theme={null}
npx skills add vercel-labs/agent-skills --skill '*' -a opencode
```

The important part is to run the command from your TeamCopilot workspace directory so the imported skills are added to the workspace-level `.agents/skills` folder.

### After import

Imported skills are not automatically ready for organization-wide use.

After importing them:

* review the imported `SKILL.md` files
* have an engineer approve them in TeamCopilot
* set permissions for specific people or **Everyone**

That approval step is what makes the imported skills usable in a controlled team environment.

## What to put in `SKILL.md`

A good skill should tell the AI a few key things:

* what the skill is for
* when it should be used
* how to perform the task well
* what rules or constraints must be followed

A practical structure is:

1. A short name and description
2. Any `required_secrets` the skill needs
3. The task or use case
4. Step-by-step instructions for the AI
5. Important rules, checks, and constraints
6. References to relevant files, scripts, systems, or docs

```mermaid theme={null}
flowchart LR
    A[Write SKILL.md] --> B[Add required secrets if needed]
    B --> C[Save in .agents/skills/<slug>/]
    C --> D[Engineer reviews diff]
    D --> E[Approve snapshot]
    E --> F[Set permissions]
    F --> G[Use skill in chat]
```

If the skill needs credentials, declare them in frontmatter and reference them by placeholder instead of raw value:

```yaml theme={null}
---
required_secrets:
  - SENDGRID_API_KEY
---
```

```text theme={null}
Use {{SECRET:SENDGRID_API_KEY}} in the Authorization header.
```

Users then add that key in **Profile Secrets**. If your team has a shared fallback, an engineer can provide it as a **Global Secret**.

If the skill references secret placeholders, keep them only in supported runtime contexts. TeamCopilot rejects unsupported secret usage instead of silently exposing values.

## What good skill instructions look like

Good skill instructions are:

* specific
* actionable
* scoped to a clear use case
* opinionated where your team has standards

Good examples:

* "Check `package.json` and `package-lock.json` versions before publishing."
* "Always review the last approved config before suggesting infra changes."
* "Summarize the issue in customer-friendly language before proposing next steps."

Weak examples:

* "Help with releases."
* "Be careful."
* "Do the right thing."

## Tips for writing better skills

* Keep one skill focused on one job or type of task.
* Prefer concrete instructions over general advice.
* Include decision rules when the AI needs to choose between options.
* Reference scripts or internal docs when they are part of the process.
* Update the skill as your team's process changes.

## Approval and access

Skills are visible in TeamCopilot, but engineer approval matters.

Before a skill becomes something the platform should rely on for team use:

* an engineer should review it
* an engineer should approve it
* access permissions should be set appropriately for your organization

This helps ensure the AI only uses reviewed instructions in production team workflows.

## What happens after approval

After approval:

* the approved snapshot is stored
* the skill can be used through chat and skill selection flows
* permissions can be updated to broaden or restrict access
* later edits will show as pending until reviewed again

## When to choose a skill instead of a workflow

Choose a skill when the main value is in the instructions themselves.

Examples:

* incident response guidance
* code review standards
* release process rules
* support escalation playbooks

If you need Python code, structured inputs, or repeatable execution, create a workflow instead.


# Creating a Workflow
Source: https://teamcopilot.ai/docs/workflows-and-skills/creating-a-workflow

Learn how to create a workflow in TeamCopilot, what files it includes, and how to turn a repeatable operational task into runnable automation.

A workflow is the right choice when you want TeamCopilot to run a repeatable task as code.

In TeamCopilot, workflows are created through the AI Assistant, then refined in the workflow editor.

## Before you create one

Create a workflow when:

* the task should run the same way every time
* you need Python code to execute the task
* the task needs structured inputs
* the task interacts with APIs, files, or external systems

If the task mainly needs instructions for the AI, create a skill instead.

## How to create a workflow

1. Open TeamCopilot.
2. Go to the **AI Assistant**.
3. Ask the assistant to create a workflow for a specific task.
4. Be clear about the workflow's purpose, inputs, and expected output.
5. After the assistant creates it, open it from the **Workflows** tab.
6. Review and edit the generated files.
7. Declare any required secret keys and configuration.
8. Have an engineer approve the workflow before running it in production.

From the product UI today, workflows are created by talking to the AI Assistant. Once created, they appear in the Workflows section where you can inspect, edit, approve, and run them.

```mermaid theme={null}
flowchart LR
    A[Create workflow] --> B[Review workflow.json]
    B --> C[Implement run.py]
    C --> D[Install dependencies]
    D --> E[Declare required secrets]
    E --> F[Engineer approves snapshot]
    F --> G[Run manually, via chat, API, or cronjob]
```

## What gets created

Each workflow lives in:

```text theme={null}
workflows/<slug>/
```

A workflow is a small package of files. The core files are:

```text theme={null}
workflows/<slug>/
├── workflow.json
├── README.md
├── run.py
├── requirements.txt
├── .venv/
└── requirements.lock.txt
```

Depending on how the workflow was generated, you may also see extra support files such as `.env` or `.env.example`. For secrets, prefer TeamCopilot secret management rather than storing raw values in those files.

## What each file does

* `workflow.json`: defines the workflow contract, including its intent, inputs, and runtime timeout
* `README.md`: documents what the workflow does and how it should be used
* `run.py`: contains the executable Python logic
* `requirements.txt`: lists Python dependencies
* `.venv/`: contains the workflow's isolated Python environment
* `requirements.lock.txt`: records the exact installed dependency versions

## The most important file: `workflow.json`

`workflow.json` defines how TeamCopilot understands the workflow.

It includes:

* `intent_summary`: a human-readable description of the workflow
* `inputs`: the parameters the workflow accepts
* `required_secrets`: the secret keys TeamCopilot must resolve before the workflow can run
* `triggers.manual`: whether it can be run manually
* `runtime.timeout_seconds`: how long it can run before timing out

This file powers both the workflow contract and the manual run UI.

The current contract is Python-based and file-system backed. If you change the execution model later, update this page first so the docs stay aligned with the actual workflow runtime.

## Writing `run.py`

`run.py` should implement one clear task end to end.

In practice, that means:

* parse inputs
* perform the workflow logic
* print useful output
* fail clearly if something goes wrong

Keep the workflow focused. If the script starts doing several unrelated jobs, it is usually time to split it into separate workflows.

## Adding dependencies and secrets

When a workflow needs external packages:

* add them to `requirements.txt`
* install them into the workflow's local virtual environment
* refresh `requirements.lock.txt`

When a workflow needs credentials:

* declare the key names in `workflow.json` under `required_secrets`
* have the user add those keys in **Profile Secrets**, or ask an engineer to provide a **Global Secret**
* read the values in `run.py` from environment variables such as `os.environ["STRIPE_SECRET_KEY"]`

Example:

```json theme={null}
{
  "intent_summary": "Create a Stripe customer",
  "required_secrets": ["STRIPE_SECRET_KEY"]
}
```

```python theme={null}
import os

stripe_key = os.environ["STRIPE_SECRET_KEY"]
```

TeamCopilot blocks runs when a required secret is missing and tells the user which key to add in **Profile Secrets**.

Do not put raw secrets in `workflow.json`, `README.md`, chat instructions, or source comments.

## Reviewing and testing a workflow

Before asking your team to use a workflow:

* check that the slug and intent still match what it does
* confirm the inputs are clear and correctly typed
* verify the timeout is reasonable
* document required setup in `README.md`
* test it with realistic inputs
* get engineer approval

After approval, users can run the workflow from TeamCopilot, including through the manual run UI for workflows with defined inputs.

## How workflows are used after creation

Workflows can be started from several places:

* the manual run screen
* chat prompts
* cronjobs
* workflow API keys

That means a good workflow should have a clear contract, strong input validation, and a focused `run.py` entrypoint.

## When to choose a workflow instead of a skill

Choose a workflow when the main value is reliable execution.

Examples:

* syncing data between systems
* generating a report
* provisioning a standard resource
* running an operational remediation step

If the main value is guidance, process, or reasoning, create a skill instead.


# Cronjobs
Source: https://teamcopilot.ai/docs/workflows-and-skills/cronjobs

Learn how scheduled prompt and workflow cronjobs work in TeamCopilot.

Cronjobs let TeamCopilot run work on a schedule.

```mermaid theme={null}
flowchart LR
    A[Scheduler fires] --> B{Prompt or workflow?}
    B -->|Prompt| C[Create or resume chat session]
    B -->|Workflow| D[Start workflow run]
    C --> E{Needs user attention?}
    E -->|Yes| F[Pause and surface session]
    E -->|No| G[Continue to completion]
    D --> H[Track workflow run status]
    H --> I[Write run history]
    F --> I
    G --> I
```

## Cronjob types

TeamCopilot supports two cronjob targets:

* **Prompt cronjobs**: scheduled agent chats that can pause for user input
* **Workflow cronjobs**: scheduled workflow runs with structured inputs

## What you can do in the UI

From the Cronjobs tab, users can:

* create a cronjob
* edit an existing cronjob
* enable or disable it
* run it immediately
* delete it
* inspect prior runs

For active runs, users can also open the run detail page and interact with controls such as interrupt, resume, or terminate when those actions are available.

## Scheduling

Cronjobs use a cron expression plus timezone.

The backend validates the schedule and computes the next run time from those settings.

## Prompt cronjobs

Prompt cronjobs create a chat session that the agent can continue over time.

They support:

* an initial prompt
* optional initial todos
* an option to allow workflow runs without extra permission
* pause and resume behavior when the agent needs user attention

Prompt cronjobs are todo-list based. That makes them useful for tasks with many smaller steps, not just one-off prompts.

TeamCopilot keeps the todo list ordered and expects the agent to complete each item in sequence. That helps prevent skipped steps, out-of-order execution, or the agent hallucinating a step that was never part of the plan.

In practice, this means prompt cronjobs can handle fairly complex operational routines as long as the task can be expressed as a clear ordered checklist.

## Workflow cronjobs

Workflow cronjobs run a specific workflow with preconfigured inputs.

They can:

* target a workflow slug directly
* include workflow input JSON
* track workflow run IDs alongside cronjob runs

## Run states

Cronjob runs can be in states such as:

* `running`
* `paused`
* `success`
* `failed`
* `skipped`
* `terminated`

The exact valid states depend on whether the cronjob is prompt-based or workflow-based.

## Runtime controls

For prompt-based runs, the UI can expose:

* interrupt
* resume
* terminate

For workflow-based runs, the UI focuses on the underlying workflow run and its history.

## Handoff behavior

If a prompt cronjob needs help from a user, TeamCopilot can reveal the hidden cronjob chat and pause the auto-continue loop until the user resumes it.

That behavior is what makes cronjobs feel like persistent operational automations rather than fire-and-forget scripts.

## State diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> Scheduled
    Scheduled --> Running: trigger fires
    Running --> Paused: user attention needed
    Paused --> Running: user resumes
    Running --> Success: completed
    Running --> Failed: error
    Running --> Terminated: user stops
    Running --> Skipped: already active or no-op
```


# Permissions
Source: https://teamcopilot.ai/docs/workflows-and-skills/permissions

Learn how to give access to specific people or everyone for skills and workflows in TeamCopilot.

TeamCopilot lets you control who can use each skill and workflow.

This is useful when:

* only certain people should run a workflow
* only certain teams should use a skill
* you want to make a reviewed resource available to everyone

## Permission modes

Skills and workflows support two permission modes:

* **Restricted**: only selected users can use the skill or workflow
* **Everyone**: anyone in TeamCopilot can use it

For workflows, this controls **run access**.\
For skills, this controls **access** to the skill.

## Before you can change permissions

Permissions can only be changed after the current version of the skill or workflow has been approved.

In practice, that means:

* create or update the skill or workflow
* have an engineer approve it
* then open the permissions editor

If the current code or instructions are still pending approval, TeamCopilot will not let you update permissions yet.

## How approval and permissions interact

Approval and permissions solve different problems:

* approval answers: "is this exact version trusted?"
* permissions answers: "who can use it?"

In practice, a resource usually needs to be approved before you make it broadly available.

## How to manage permissions

1. Open the **Skills** or **Workflows** tab.
2. Find the skill or workflow you want to update.
3. Open **Manage Permissions**.
4. Choose a permission mode:
   * **Restricted (Specific Users)**
   * **Everyone**
5. If you choose **Restricted**, select the users who should have access.
6. Save your changes.

## Giving access to specific people

Use **Restricted** when a skill or workflow should only be available to a defined set of users.

This is the right choice when:

* a workflow can make operational or production changes
* a skill contains sensitive internal procedures
* only a specific team should use the resource

When a resource is restricted:

* only the selected users can use it
* the owner remains included
* the permission list must contain at least one allowed user

In the TeamCopilot UI, the owner cannot be unchecked in restricted mode.

If a resource loses all allowed users, TeamCopilot treats it as locked. That prevents a permission change from bricking access to the resource.

## Giving access to everyone

Use **Everyone** when the skill or workflow is safe and broadly useful across the organization.

This is the right choice when:

* the workflow is low-risk and generally useful
* the skill captures guidance the whole team should follow
* you want to reduce permission management overhead

When a resource is set to **Everyone**, any TeamCopilot user can access it.

## Who can change permissions

Only users who already have access to a skill or workflow can change its permissions.

That means:

* if you can use the resource, you can manage its permissions
* if you do not have access, you cannot change who gets access

If a restricted resource somehow ends up with no allowed users remaining, TeamCopilot treats it as locked and permissions can no longer be modified through the normal UI flow.

## Missing users and missing secrets

The UI also marks a resource as locked or partially unavailable when:

* the resource references users who no longer exist
* the resource requires secrets the current user has not added

This is why a resource listing can show both access state and secret readiness.

## Recommended approach

For most organizations:

* start new skills and workflows as **Restricted**
* give access to the people who should validate them first
* switch to **Everyone** only after you are confident the resource is safe for broader use

This keeps rollout controlled without making the system hard to use.

## A simple rule of thumb

Use **Restricted** for sensitive, high-impact, or team-specific resources.

Use **Everyone** for reviewed resources that are safe and useful across the organization.


# Run History
Source: https://teamcopilot.ai/docs/workflows-and-skills/run-history

Learn how to inspect past workflow runs, cronjob runs, and execution logs in TeamCopilot.

TeamCopilot keeps run history so you can inspect what happened after the fact.

```mermaid theme={null}
flowchart LR
    A[Workflow starts] --> B[Backend stores run record]
    B --> C{Run finishes?}
    C -->|Yes| D[Store output, status, timestamps]
    C -->|No| E[Keep polling run detail page]
    D --> F[Visible in run history]
    F --> G[Open run details]
```

## What the history view shows

The run history tab lists recent workflow runs with:

* workflow slug
* status
* start time
* duration
* runner identity

The current implementation shows the workflow slug, status, start time, duration, and runner identity. The detail page then shows input and logs.

## Run detail pages

Each run has a dedicated detail page where you can inspect:

* the run summary
* the captured output
* the associated logs
* the originating session when available

The run detail view is the right place to debug a failed workflow or confirm what happened during a long-running operation.

### What the detail page includes

* workflow slug
* run status
* runner identity
* started and completed timestamps
* duration
* parsed input payload
* captured logs
* a stop button when the run is still active

## Log sources

TeamCopilot can fetch logs either from the workflow run record or from a session/message pair, depending on how the run was created.

## Relationship to cronjobs

If a workflow run was started by a cronjob, the run history may be the first place you notice it. Cronjob runs can point back to the workflow run, and the workflow run detail page is where you inspect the runtime output.

## When history matters

Use run history when you need to:

* audit what ran
* review a failure after the fact
* navigate from cronjob execution back to the underlying workflow run
* compare multiple runs of the same workflow


# Running Skills and Workflows
Source: https://teamcopilot.ai/docs/workflows-and-skills/running-skills-and-workflows

Learn the recommended ways to use skills and workflows in TeamCopilot, whether through natural language, skill shortcuts, or manual workflow runs.

For most teams, the best way to use skills and workflows is simple: **talk to the AI Assistant in natural language**.

In many cases, you do not need to think about whether the AI should use a skill, a workflow, or both. You can just describe what you want, and TeamCopilot will try to find the right skill or workflow for the task.

## Running skills

The recommended way to use a skill is to ask for what you want in plain language.

For example, you can say things like:

* "Review this release plan using our release process."
* "Use our incident response skill to help triage this issue."
* "Help me prepare an RCA in the format our team uses."

If a matching skill already exists, TeamCopilot will try to find it and apply it.

If you already know the resource slug, the UI also supports direct navigation to the skill page and approval review page.

### Using a skill shortcut

If you know exactly which skill you want, you can also invoke it directly with its shortcut name.

In the current TeamCopilot setup, this is typically written as:

```text theme={null}
/skill-name
```

For example:

```text theme={null}
Use /release-teamcopilot-npm to dry-run the npm release for this repo.
```

This is useful when:

* you already know which skill should be used
* you want predictable behavior from a specific skill
* your team uses named skills regularly

### If you are not sure which skill to use

You can simply describe the task. TeamCopilot will try to find the most relevant skill for you.

That means you can say:

* what you are trying to do
* what outcome you want
* any important constraints or context

This is usually the easiest and most natural way to work.

## Running workflows

You can also ask the AI Assistant to run a workflow for you in natural language.

For example:

* "Run the customer-report workflow for account 123."
* "Use the deployment workflow for staging."
* "Run our sync workflow with yesterday's data."

If you know the exact workflow you want, you can say so directly. If you do not, you can still describe the task and let the AI try to find the right workflow.

## Other workflow entry points

Workflows can also be:

* run manually from the workflow page
* run from cronjobs
* run remotely through a workflow API key
* resumed from a cronjob handoff session when the run pauses for attention

## Calling workflows via APIs

TeamCopilot also supports API access for workflows through workflow-specific API keys.

If you want the dashboard to show curl commands with the correct public host, set `EXTERNAL_HOST` in the TeamCopilot environment.

* When `EXTERNAL_HOST` is set, TeamCopilot uses it as the base URL for API examples.
* When it is not set, TeamCopilot falls back to `TEAMCOPILOT_HOST` and `TEAMCOPILOT_PORT`.
* Use a public or externally reachable host value here if people will copy the curl commands from the dashboard.

Example:

```bash theme={null}
EXTERNAL_HOST=https://teamcopilot.example.com
```

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant API as Workflow API
    participant B as Backend runner

    C->>API: POST /runs with bearer key
    API->>API: Validate key and workflow slug
    API->>B: Start workflow run
    B-->>API: Return run handle
    API-->>C: run_handle
    C->>API: GET /runs/:runHandle
    API-->>C: status + logs + inputs
```

### What workflow API keys do

A workflow API key lets an external caller:

* trigger a workflow run
* query the run status
* stop a running workflow

The key is bound to a single workflow slug.

### Approval requirement

Workflow API keys are only available once the workflow's current snapshot is approved.

That prevents unreviewed workflow code from being exposed as an external API surface.

### Typical flow

1. Open the workflow page.
2. Generate an API key for the workflow.
3. Use the key to submit a remote run.
4. Poll the run status until it completes.
5. Stop the run if needed.

### API reference

#### Start a run

```bash theme={null}
curl -X POST "https://teamcopilot.example.com/api/workflow-api/runs" \
  -H "Authorization: Bearer <workflow-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_slug": "deploy-report",
    "inputs": {
      "environment": "staging"
    }
  }'
```

Response:

```json theme={null}
{
  "run_handle": "workflow-run-id"
}
```

#### Check run status

```bash theme={null}
curl "https://teamcopilot.example.com/api/workflow-api/runs/workflow-run-id" \
  -H "Authorization: Bearer <workflow-api-key>"
```

Response fields include:

* `run_handle`
* `workflow_slug`
* `status`
* `logs`
* `error_message`
* `started_at`
* `completed_at`
* `inputs`

#### Stop a run

```bash theme={null}
curl -X POST "https://teamcopilot.example.com/api/workflow-api/runs/workflow-run-id/stop" \
  -H "Authorization: Bearer <workflow-api-key>"
```

### Constraints

* the API key must belong to the same workflow being run
* the workflow must be approved before the key can be created or used
* each workflow must always keep at least one API key

## Running a workflow manually

Workflows can also be run manually from the **Workflows** tab.

This is useful when:

* you want to choose the workflow yourself
* you want to provide inputs explicitly in the UI
* you want a more structured run flow than chat

To run a workflow manually:

1. Open the **Workflows** tab.
2. Select the workflow you want.
3. Open the manual run screen.
4. Fill in any required inputs.
5. Start the workflow.

After the run starts, TeamCopilot tracks it through the workflow run system.

## Recommended approach

For day-to-day use:

* start with natural language in the **AI Assistant**
* use a named skill shortcut when you know the exact skill you want
* use manual workflow runs when you want explicit control over workflow inputs

This gives most teams the best balance of speed, flexibility, and control.


# Secret Management
Source: https://teamcopilot.ai/docs/workflows-and-skills/secret-management

Learn how users add secrets in TeamCopilot, how skills and workflows reference them, and why the secret proxy model is safer than putting raw keys in agent context.

In TeamCopilot, users do not paste raw secrets into workflow files or skill instructions.

Instead, you store secrets in TeamCopilot, then reference them by key name from skills and workflows.

<Check>
  <strong>TeamCopilot never injects a secret into the LLM chat history.</strong> The model gets secret names and placeholders, while the real values are resolved only by trusted runtime layers at execution time.
</Check>

```mermaid theme={null}
flowchart TB
    A[Skill or workflow declares secret keys] --> B{User secret exists?}
    B -->|Yes| C[Use profile secret]
    B -->|No| D{Global secret exists?}
    D -->|Yes| E[Use global secret]
    D -->|No| F[Block run and show missing keys]
```

## What you need to do

If a skill or workflow needs a secret:

1. Open **Profile Secrets** in TeamCopilot.
2. Add the required key, such as `OPENAI_API_KEY` or `STRIPE_SECRET_KEY`.
3. Save it.
4. Retry the skill or workflow.

If your organization uses shared fallback secrets, an engineer can also add **Global Secrets**. Your personal secret overrides the global one when both use the same key.

## Where secrets live

TeamCopilot supports two secret scopes:

* **Profile Secrets**: your personal secrets for your own runs
* **Global Secrets**: shared fallback secrets managed by engineers

This gives teams a practical default:

* regular users add their own keys in **Profile Secrets**
* engineers can provide shared defaults in **Global Secrets**
* a user's personal key wins over the global key with the same name

That override model is useful when you want to test with your own account without changing the team's default credential.

## Profile Secrets UI

Users manage profile secrets from the dedicated `Profile Secrets` page in the app.

The page shows:

* the keys you have saved
* masked values in normal UI contexts
* actions to add, edit, or delete a key

## Global Secrets UI

Engineers manage global secrets from the same page, in a separate section.

That makes the common pattern straightforward:

* users add personal overrides
* engineers provide shared defaults
* the runtime resolves the best value at execution time

## How skills and workflows ask for secrets

Skills and workflows declare the secret keys they need by name.

### Skills

In `SKILL.md`, declare `required_secrets` in frontmatter and use `{{SECRET:KEY}}` placeholders in the content.

```yaml theme={null}
---
title: "Send campaign email"
required_secrets:
  - SENDGRID_API_KEY
---
```

```text theme={null}
Use this header in bash commands:
Authorization: Bearer {{SECRET:SENDGRID_API_KEY}}
```

### Workflows

In `workflow.json`, declare the required secret keys:

```json theme={null}
{
  "intent_summary": "Create an invoice in Stripe",
  "required_secrets": ["STRIPE_SECRET_KEY"]
}
```

Then read them in `run.py` as environment variables:

```python theme={null}
import os

stripe_key = os.environ["STRIPE_SECRET_KEY"]
```

If a required secret is missing, TeamCopilot tells the user which key to add in **Profile Secrets** before the skill or workflow can run.

## How TeamCopilot keeps secrets out of the model

The core rule is simple: the agent sees secret names, not secret values.

For bash-based usage, TeamCopilot uses a secret proxy pattern:

1. The skill or command references `{{SECRET:KEY}}`.
2. A trusted runtime layer checks where that placeholder is being used.
3. If the usage is allowed, TeamCopilot injects the real value only at execution time.
4. The raw value does not need to appear in the prompt, command text, or normal UI output.

For workflows, the workflow declares `required_secrets`, and TeamCopilot resolves those values for the current user at runtime.

For chat sessions, the app can also resolve secrets on demand for trusted runtime flows such as command execution or skill loading.

## Command support today

As of now, TeamCopilot also injects secret values for `curl` and `git` commands when the agent uses them through bash.

That means a command like:

```bash theme={null}
curl -H "Authorization: Bearer {{SECRET:API_TOKEN}}" https://example.com
```

or:

```bash theme={null}
git push https://{{SECRET:GIT_TOKEN}}@github.com/org/repo.git
```

can resolve the secret at execution time without exposing the raw value in chat history.

## Extending command support

If you want support for more bash commands, email `rishabh@trythis.app`, or create a [github pull request](https://github.com/rishabhpoddar/teamcopilot).

Another safe option is to wrap the command in a workflow. Workflows are pre-approved before use, so TeamCopilot can inject secrets into them however the workflow needs without exposing those values to the model.

## Runtime resolution order

The resolution order is:

1. profile secret
2. global secret fallback
3. missing-key error

That order makes personal overrides predictable without breaking shared defaults.

## What this protects against

This design is meant to reduce the most common AI-agent secret leaks.

* **Prompt injection**: if an attacker gets hidden instructions in front of the model, the model still does not have the plaintext key to leak
* **Unsafe command construction**: secret placeholders are only resolved in trusted positions; unsupported usage is rejected
* **UI exposure**: the frontend shows masked values instead of raw credentials
* **Cross-user leakage**: one user can use a shared or personal secret without seeing another user's actual key

## Engineer approval still matters

Workflows and skills can use secrets only after their code or instructions have been reviewed in TeamCopilot.

That approval step matters most for workflows, because workflows can use the resolved secret values directly in code. The trust boundary is the reviewed artifact plus the runtime that injects secrets without exposing them to the model.


# Token usage analytics
Source: https://teamcopilot.ai/docs/workflows-and-skills/token-usage-analytics

Use the token usage dashboard to review estimated cost, token counts, and usage trends over time.

TeamCopilot exposes **token usage analytics** in the web app: estimated spend, token volumes, and how they move day by day. The dashboard is about **usage and cost**, not individual users or org-wide adoption metrics.

## What you can see

In the TeamCopilot web app, open the **Token Usage** tab. You get:

* **Summary metrics** for the selected period:
  * **Estimated cost** — approximate cost from model usage
  * **Total tokens** plus **input**, **output**, and **cached** token counts
  * **Tracked sessions** — how many sessions the aggregates are based on (context for the token totals, not a separate “team” report)
* **Charts over time**:
  * **Estimated cost over time** — daily bars to compare spend across days
  * **Token usage over time** — stacked bars by token type per day on the same timeline

Together, these help you see spikes in cost or tokens, compare one day to another, and see how much traffic is served from **cache** versus fresh **input**/**output** tokens.

The totals are derived from tracked chat sessions in the workspace database.

## How cost is calculated

TeamCopilot calculates estimated cost from the configured model and the token counts recorded for each completed assistant message.

Pricing is applied per million tokens for:

* input tokens
* cached input tokens
* output tokens

In case you are seeing `$0` as the cost, or you are not seeing cost at all, you need to add these pricing env vars to the TeamCopilot setup:

* `TEAMCOPILOT_MODEL_INPUT_PER_MILLION_USD`
* `TEAMCOPILOT_MODEL_CACHED_INPUT_PER_MILLION_USD`
* `TEAMCOPILOT_MODEL_OUTPUT_PER_MILLION_USD`

All three values must be set together. If only one or two are set, TeamCopilot throws an error and will not use the partial override.

These values tell TeamCopilot how to calculate estimated cost for the currently configured `OPENCODE_MODEL`.

If no supported pricing is available for the configured model, the dashboard shows that pricing is unavailable and estimated cost may be `0` for those entries.

## Time ranges

Use the range control at the top (for example **24 hours**, **7 days**, **30 days**, or **90 days**). Summary figures and charts all use that window.

## Accuracy and limitations

Figures are **estimates derived from tracked sessions**. Some activity may be missing from the totals. Use them for trends and rough budgeting, not as an exact bill.

## Screenshot

The **Token Usage** tab, showing cost and token analytics:

<img alt="Token Usage tab showing estimated cost, token metrics, and cost/token charts over time" />