<!-- prettier-ignore -->
<div align="center">

<img src="./icons/icon.png" alt="aidget icon" width="96" />

# aidget

**Manage desktop widgets — the AI Agent way.**

[![CI](https://img.shields.io/github/actions/workflow/status/aidget-ai/aidget/check.yml?branch=main&label=CI&style=flat-square)](https://github.com/aidget-ai/aidget/actions/workflows/check.yml)
[![Latest release](https://img.shields.io/github/v/release/aidget-ai/aidget?style=flat-square)](https://github.com/aidget-ai/aidget/releases/latest)
[![Rust 1.92+](https://img.shields.io/badge/Rust-1.92%2B-b7410e?style=flat-square&logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![Tauri 2](https://img.shields.io/badge/Tauri-2-24c8db?style=flat-square&logo=tauri&logoColor=white)](https://tauri.app/)
[![MCP](https://img.shields.io/badge/MCP-stdio-6b7280?style=flat-square)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-111111?style=flat-square)](LICENSE)

[Quick start](#quick-start) | [Cross-platform support](#cross-platform-support) | [Development](#development) | [Data directory](#data-directory) | [Permission controls](#permission-controls)<br>
English | [简体中文](README.zh-CN.md)

<table width="100%">
  <tr>
    <td width="50%" align="center">
      <img src="./screenshot.webp" alt="aidget main window" width="100%" />
      <sub>Main window</sub>
    </td>
    <td width="50%" align="center">
      <img src="./screenshot-desktop.webp" alt="aidget widgets on the desktop" width="100%" />
      <sub>Widgets on the desktop</sub>
    </td>
  </tr>
</table>

</div>

## Is aidget for you?

If your desktop feels lifeless and you already use a desktop agent such as ChatGPT, Claude, or Grok Bot, aidget can help your agent bring it to life.

Connect aidget to your agent, describe your ideas in natural language, and give your desktop a fresh look.

Some typical scenarios:

- **Sticky notes.** Ask your agent to create a personalized sticky note on the desktop and keep track of the day's tasks.
- **Weather widget.** Ask your agent to recreate the macOS weather widget with a live forecast.
- **Desktop pet.** Let your agent look after a digital pet and watch what it does.
- **Anniversary card.** Ask your agent to create a card for an important date so you never miss it.
- **Stock tracker.** Ask your agent to display the stocks you follow so you never miss a market update.

More ideas are waiting to be discovered!

## Cross-platform support

- **macOS 12+**: Apple Silicon (arm64) and Intel (x64)
- **Windows 10 (1803+)**: x64
- **Windows 11**: x64 and ARM64
- **Linux**: Ubuntu 22.04+, Debian 12+, Fedora 37+, and openSUSE Tumbleweed (x64 and ARM64)

## Quick start

### 1. Install

Download and launch the build for your operating system from [GitHub Releases](https://github.com/aidget-ai/aidget/releases/latest).

> ⚠️ macOS and Windows packages are currently unsigned and may trigger Gatekeeper or SmartScreen warnings. Builds downloaded from GitHub Releases are the official builds.

Launching aidget opens the main window; you can also access it from the system tray. On first launch, aidget places a welcome widget on the desktop, so keep an eye out.

### 2. Connect an agent

> aidget detects common local agent applications. Any MCP-compatible client can also connect manually.

1. Open the **MCP & Skills** page.
2. Click the icons to connect **MCP Service** and **Agent Skill** for detected agents. Installing both is recommended.
3. If your agent does not detect the MCP server or the `aidget` Skill, restart it to reload the configuration.

### 3. Ask your agent to create a widget

Return to the agent chat you normally use and describe what you want, for example:

```text
/aidget Create an Ace of Hearts playing card as a desktop widget.
```

Or a scheduled task:

```text
/aidget Create a stock-tracking widget and check the latest Apple stock details every 5 minutes.
```

## Community widgets

Install community widgets that have passed security review from the **Community Widgets** panel.

Community widgets are maintained in [aidget-ai/widgets](https://github.com/aidget-ai/widgets). Visit that repository to learn how to contribute.

## Development

### Requirements

- Rust 1.92 or newer
- Node.js 22.18+ (22.x) or 24.11+ (24.x)
- pnpm 12
- Tauri 2 platform prerequisites
- Linux: `libwebkit2gtk-4.1-dev`, `libayatana-appindicator3-dev`, and `librsvg2-dev`

### Run locally

```bash
git clone https://github.com/aidget-ai/aidget.git && cd aidget
pnpm install
pnpm dev
```

> `pnpm dev` uses the repository's `.aidget/` directory by default, separate from an installed copy. Override it with `--home` when needed:
>
> `pnpm dev --home /tmp/aidget-dev`

### Build

```bash
pnpm build             # production release bundle
pnpm build:debug       # debug app bundle
```

### Checks

```bash
pnpm check
pnpm test
```

Detailed architecture, interfaces, runtime checks and repository-specific
workflows are in [docs/development.md](docs/development.md). Contribution rules
and PR requirements are in [docs/contributing.md](docs/contributing.md).

## Data directory

The default data root is `~/.aidget` (`C:\Users\<user>\.aidget` on Windows).

```text
~/.aidget
├── aidget[.exe]              # CLI symlink on macOS/Linux; executable copy on Windows
├── board.json                # widget positions and sizes
├── settings.toml             # application settings
├── run/                      # runtime IPC endpoint (Unix socket on macOS/Linux)
├── widgets/
│   └── <id>/
│       ├── package.json      # optional npm package metadata (for publishing to npm)
│       ├── config.json       # widget configuration and state
│       ├── index.html        # widget structure
│       ├── style.css         # appearance, size, and layout styles
│       ├── agents.md         # guidance for future agents
│       └── assets/           # images, fonts, and other local assets
├── state/
│   ├── agent-backups/        # agent configuration backups made during integration
│   ├── community/
│   │   ├── downloads/        # npm download statistics cache
│   │   ├── media/            # community logos and screenshots cache
│   │   └── registries/       # community catalog cache
│   ├── previews/
│   │   └── <id>.png          # cached widget previews for the main window
│   ├── screenshots/          # widget screenshots
│   ├── storage/
│   │   └── <id>.json         # persistent widget data
│   └── migrations/           # migration completion marker
├── skills/
│   └── aidget/
│       └── SKILL.md          # the Skill distributed to agents
└── trash/                    # deleted widgets retained for restoration
```

## Permission controls

aidget includes a permission model to improve runtime security.

### Permissions

Declare the permissions a widget needs in its `config.json` using `permissions`. The default is an empty list, granting no capabilities.

```
{
  "permissions": [
    "script",
    "storage",
    ...
  ]
}
```

- `script`: allows package-local scripts and inline `<script>` blocks already present in the served HTML. Inline blocks are authorized by content hashes. Remote scripts, `eval`, `new Function`, inline event attributes and `javascript:` URLs are blocked; use `addEventListener` for events. Without this permission, CSP blocks widget scripts. Widgets remain in a sandbox without same-origin access and cannot read other widgets' files or control the main window. Nested pages, objects and workers are always blocked.
- `storage`: provides local storage isolated per widget, with a 256 KB limit.
- `location`: lets a widget request the operating system's location service when it needs location information.

## Network permissions

Declare the exact HTTPS origins a widget can access in its `config.json` using `network`. The default empty list blocks network access. Grants cover API requests, images, styles, fonts and media; they never authorize remote JavaScript.

```
{
  "network": [
    "https://example.com"
  ]
}
```

### Security statement

aidget does not store model credentials, and prompts, replies and model keys do not pass through aidget (except for proactively configured GitHub access tokens).

See [SECURITY.md](SECURITY.md) for the vulnerability reporting process.

## License

[MIT License](LICENSE)