timebase — GitHub Copilot plugin: what it does, how to install

# TimeBase Agent Plugins

TimeBase plugins for Cursor, VSCode, Claude Code, OpenAI Codex, Gemini CLI, Antigravity CLI, and any tool supporting the Open Plugin standard.

Includes MCP tools and skills for QQL, TimeBase client development, WebAdmin integration, and troubleshooting.

If you only need skills, jump to [Skills](#skills).

## Quickstart

### 1. Install uv

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if `uvx` is not available.

Check that `uvx` is available in your shell:

```bash
uvx -V
```

### 2. Install plugin in your tool

<details>
<summary>Cursor</summary>

Clone this repository as a local plugin.

macOS/Linux:

```bash
git clone https://github.com/epam/TimeBase-Agent-Plugins.git ~/.cursor/plugins/local/timebase
```

Windows:

```bash
git clone https://github.com/epam/TimeBase-Agent-Plugins.git %USERPROFILE%\.cursor\plugins\local\timebase
```

Open `Cursor Settings > Plugins > TimeBase Plugin > TimeBase MCP` to edit configuration.  
Available options: [MCP configuration](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md).

</details>

<details>
<summary>VSCode</summary>

Search for `@agentPlugins timebase` in the Extensions tab to install.

For adjusting the settings open the chat panel, click `Configure Tools`, hover over `timebase-mcp`, then click `Configure TimeBase`.
Available options: [MCP configuration](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md).

</details>

<details>
<summary>Claude Code</summary>

Open a terminal and run:

```bash
claude plugin marketplace add epam/TimeBase-Agent-Plugins
claude plugin install timebase@timebase-plugins
```

You will be able to configure MCP by running `/plugins` inside a Claude Code session, selecting the plugin under `Installed` and clicking `Configure options`.  
Available options: [MCP configuration](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md).

</details>

<details>
<summary>Claude Desktop</summary>

Open `Settings > Plugins > Add > Add Marketplace` and paste:

```
epam/TimeBase-Agent-Plugins
```

Press `Sync` button and wait for the plugin list to appear.

Select `TimeBase` and click the `+` to install.

</details>

<details>
<summary>OpenAI Codex</summary>

From your terminal, run:

```bash
codex plugin marketplace add epam/TimeBase-Agent-Plugins
codex plugin add timebase@timebase-plugins
```

Then start a new Codex instance so the plugin skills and MCP tools are loaded.

The MCP server settings can be configured globally in `~/.codex/config.toml` or per project in `.codex/config.toml`:

```toml
[plugins."timebase@timebase-plugins".mcp_servers.timebase.env]
TIMEBASE_URL = "dxtick://localhost:8011"
```

Check out the available [MCP configuration options](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md).

</details>

<details>
<summary>GitHub Copilot CLI</summary>

In your terminal, run:

```bash
copilot plugin install timebase@awesome-copilot
```

Then start a new Copilot CLI session so the plugin is loaded.

Adjust the MCP server settings via `/mcp edit timebase-mcp` command. 
Check out the available [MCP configuration options](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md).

</details>

<details>
<summary>GitHub Copilot App</summary>

Use the following button:

[![Install TimeBase plugin](https://img.shields.io/badge/Install-TimeBase_Plugin-blue?logo=github&style=flat-square)](ghapp://plugins/marketplace/add?source=epam%2FTimeBase-Agent-Plugins)

Or go to `Settings > Plugins` and search for `timebase`.

</details>

<details>
<summary>Gemini CLI</summary>

From your terminal, run:

```bash
gemini extensions install https://github.com/epam/TimeBase-Agent-Plugins
```

Then restart any pre-existing Gemini CLI sessions so the extension is loaded.

Extension exposes the main [TimeBase MCP environment variables](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md) as install-time settings.

To configure extension settings later, run:

```bash
gemini extensions config timebase
```

</details>

<details>
<summary>Antigravity CLI</summary>

From your terminal, run:

```bash
agy plugin install https://github.com/epam/TimeBase-Agent-Plugins
```

Then start a new Antigravity CLI session so the plugin is loaded.

Check out the available [TimeBase MCP environment variables](https://github.com/epam/TimeBase-MCP/blob/main/docs/reference/environment-variables.md) for the full list of supported options.

</details>

<details>
<summary>Other tools</summary>

This repository follows the [Open Plugin](https://open-plugins.com/) standard, so it can be used in any compatible tool.

</details>

> [!NOTE]
> If you encounter issues with the MCP server, check out the [troubleshooting guide](https://github.com/epam/TimeBase-MCP/blob/main/docs/troubleshooting.md).

### Updating an existing plugin installation

Updating the plugin updates the pinned TimeBase MCP version. You do not need to update TimeBase MCP separately.

<details>
<summary>Cursor</summary>

If you cloned the plugin locally, pull the latest changes:

macOS/Linux:

```bash
git -C ~/.cursor/plugins/local/timebase pull
```

Windows:

```bash
git -C %USERPROFILE%\.cursor\plugins\local\timebase pull
```

</details>

<details>
<summary>VSCode</summary>

VS Code updates plugins automatically every 24 hours by default. To trigger an update manually, open command palette (CMD+Shift+P / Ctrl+Shift+P) and run `Extensions: Check for Extension Updates`.

</details>

<details>
<summary>Claude Code</summary>

Inside Claude Code session run:

```bash
/plugin
```

Navigate to the installed plugin and click `Update` button.

</details>

<details>
<summary>Claude Desktop</summary>

Use the `Settings > Plugins > TimeBase > Update` button.

</details>

<details>
<summary>OpenAI Codex</summary>

Refresh the marketplace snapshot and reinstall the plugin:

```bash
codex plugin marketplace upgrade timebase-plugins
codex plugin add timebase@timebase-plugins
```

Then restart any running Codex instances.

</details>

<details>
<summary>GitHub Copilot CLI</summary>

In your terminal, run:

```bash
copilot plugin update timebase
```

Then restart any running Copilot CLI sessions.

</details>

<details>
<summary>GitHub Copilot App</summary>

Go to `Settings > Plugins`, find `timebase` and click `Update plugin` under the 3-dot menu.

</details>

<details>
<summary>Gemini CLI</summary>

In your terminal, run:

```bash
gemini extensions update timebase
```

Then restart any running Gemini CLI sessions.

</details>

<details>
<summary>Antigravity CLI</summary>

Antigravity CLI doesn't have a built-in update command. To update the plugin, follow the installation instructions again.

</details>

<details>
<summary>Other tools</summary>

Refer to your tool's documentation for updating plugins installed from a repository source.

</details>

## Skills

> [!NOTE]
> The plugin includes the skills and TimeBase MCP. Installing skills separately does not install MCP.
> QQL validation and live runtime inspection need a reachable TimeBase server. Troubleshooting with `search_logs_kb` requires TimeBase MCP 0.2.5 or later, but the bundled knowledge base can be searched without a live TimeBase connection.

### Prerequisites

- **Node.js** installed for `npx skills`.

### Installation

#### npx skills (recommended)

Works for Claude Code, Cursor, VSCode and any other tool supporting the [Agent Skills](https://agentskills.io/home) open standard.

```bash
npx skills add https://github.com/epam/TimeBase-Agent-Plugins.git
```

> [!WARNING]
> Doesn't work for Claude Desktop, use the manual installation path below instead.

#### Manual installation

Download the desired `<skill-name>.zip` from the [latest release](https://github.com/epam/TimeBase-Agent-Plugins/releases/latest).

Claude Desktop accepts the ZIP directly. Open `Settings > Skills > Add > Upload skill`.

For other tools, extract the ZIP and copy its `<skill-name>` directory into your tool's skills installation folder.

You can also clone this repository instead of downloading a ZIP:

```bash
git clone https://github.com/epam/TimeBase-Agent-Plugins.git
```

Then copy `skills/<skill-name>` directory into your tool's skills installation folder.

### Usage

No special actions are required. Just ask your agent something about QQL.

### Updating

To update skills you already installed from this repository:

```bash
npx skills update
```

To install a newly added skill from this repository, run the installation command again or copy the new skill directory manually.

### Uninstallation

```bash
npx skills remove
```