> ## Documentation Index
> Fetch the complete documentation index at: https://gugu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribute gugu Apps

> Build your first App, test it, then submit a pinned version to the market index.

An App is a folder holding a manifest, pages, and optional programs. It can add work pages to tasks, let a group edit files together, or give Agents tools and skills. Users choose which regular Apps to install.

This chapter covers getting started, the API, debugging, submission, and maintenance. Start with a notes App that saves a draft, then add shared files or Agent tools as needed. For installation and permissions from the user's side, see [App](/en/apps).

> [!NOTE]
>
> This chapter reflects the development build as of 2026-10-21. The current App API is 9, and the minimum supported is 3. The stable release and Beta may expose different APIs. Check the target client before installing, and state compatibility requirements when you publish.

## Prerequisites

You need a computer with the gugu desktop app and a text editor. This example has no build step and does not need Node. Git, Node.js, and a GitHub account are only needed when you submit to the market.

If you want an Agent in gugu to write it for you, first have it read the `apps` and `apps-ui` topics with `guide_read`. Then have it read the topics listed in the [API overview](/en/extension-api) for the features you need. You can also build the package in an external editor; a person then installs it in gugu.

## Build a notes App

Create a `notes-starter` folder and add the three files below. The complete, copyable folder is in the [starter sample in the docs repository](https://github.com/shuxueshuxue/gugu-docs/tree/4ac2879596e275ee2334551808f338904344be54/samples/app-starter). The sample keeps its Chinese interface strings: the tab title 便签 means "Notes", and 保存 is "Save". Replace them with your own wording.

```text theme={null}
notes-starter/
  manifest.json
  main.html
  main.js
```

`manifest.json` declares the name, version, and page. It requests no extra permissions.

```json theme={null}
{
  "id": "notes-starter",
  "name": "便签起步",
  "description": "在 App 页面里保存一份本机草稿。",
  "version": "1.0.0",
  "apiVersion": 9,
  "engines": { "gugu": ">=0.2.57" },
  "entry": "main.html",
  "contributes": {
    "tabs": [{ "name": "notes", "title": "便签", "entry": "main.html" }]
  }
}
```

`main.html` uses the page styles gugu provides. The script lives in a separate file.

```html theme={null}
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>便签起步</title></head>
<body>
  <main>
    <h1>便签</h1>
    <label for="draft">本机草稿</label>
    <textarea id="draft" rows="8"></textarea>
    <button id="save" type="button">保存</button>
    <p id="status" role="status"></p>
  </main>
  <script src="main.js"></script>
</body>
</html>
```

`main.js` saves the draft and shows any read or write failure.

```js theme={null}
const draft = document.getElementById('draft');
const statusLine = document.getElementById('status');

try {
  draft.value = localStorage.getItem('draft') ?? '';
} catch (error) {
  statusLine.textContent = `读取失败：${error.message}`;
}

document.getElementById('save').addEventListener('click', () => {
  try {
    localStorage.setItem('draft', draft.value);
    statusLine.textContent = '已保存到这个 App 的本机存储';
  } catch (error) {
    statusLine.textContent = `保存失败：${error.message}`;
  }
});

window.gugu.getContext().then((context) => {
  document.documentElement.lang = context.locale || 'zh-CN';
}).catch((error) => {
  statusLine.textContent = `读取 App 环境失败：${error.message}`;
});
```

## Install and check

1. In gugu's App management, choose to install from a folder and select `notes-starter`.
2. Open the **便签** (Notes) tab, type "Organize the literature tomorrow", click **保存** (Save), and confirm the save result appears.
3. Close the App and reopen it. Confirm the same text is still there. The draft is stored on this device and does not sync across devices or group members.
4. Switch between light and dark themes and narrow the page. Check that the label, text box, and button still work.

A package that requests permissions shows a confirmation sheet, and the user decides whether to grant them. An Agent in gugu can use `app_create`, `app_install`, and `app_check` to build, install, and check an App. Declaring a permission does not grant it. For detailed steps, see [Development and debugging](/en/apps/development).

## Next steps from the sample

| What you want to do | Next step |
| - | - |
| Change the name, entry, permissions, or minimum version | [manifest](/en/apps/manifest) |
| Read files, give Agents tools, collaborate with others | [API overview](/en/extension-api) |
| See how real projects are organized | [Paper Club](https://github.com/shuxueshuxue/gugu-apps/tree/main/sources/paper-club), [Kanban](https://github.com/shuxueshuxue/gugu-apps/tree/main/sources/kanban), [Forum](https://github.com/shuxueshuxue/gugu-apps/tree/main/sources/forum) |
| Publish an installable version | [Submit to the market](/en/apps/publishing) |
| Ship a new version, withdraw, or stop maintaining | [Maintenance and updates](/en/apps/maintenance) |

There is currently no separate official App template repository. This page gives a copyable folder, and real Apps are in `sources/` of the market index repository. When copying, keep the licenses required by the code and dependencies you use, and replace the identifiers with your own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.