# Kibbles Overview

> **New here?** Start with [Get started](https://nana.areshk.dev/docs/extensions/get-started.md).

A kibble is a web project that adds to the desktop app: tabs, panels,
popovers, a sidebar, top bar and status bar items, palette commands, shortcuts,
background logic, and app languages. You build it with any web tooling and Nana
loads the build output.

Kibbles are Nana's extensions. The API, manifest, and folders still use the
word `extension`, for example `nana.extensionID` and `extension.` events.

## Where code runs

| Where | What it is | API |
| --- | --- | --- |
| **Pages** | Tabs, panels, popovers, the sidebar, and modal web views. The system's own engine, `WebView2`, in a native host over the app, alive while hidden. | `window.nana`, async (Promises) |
| **Scripts** | A `runScript` command. Runs once in QuickJS on its own thread. | `nana`, synchronous |
| **Background** | The optional `background` script. Runs while the kibble is enabled. Receives events. | `nana`, synchronous |

Not every API exists everywhere. See the [API reference](https://nana.areshk.dev/docs/extensions/api.md#availability).

File, Git, and `exec` work runs on the project's server, so it works the same
for local and remote projects. Web requests run in the desktop app.

## Pages

| Page | What's in it |
| --- | --- |
| [Get started](https://nana.areshk.dev/docs/extensions/get-started.md) | Build, load, and debug a kibble |
| [Manifest](https://nana.areshk.dev/docs/extensions/manifest.md) | `package.json` fields |
| [Permissions](https://nana.areshk.dev/docs/extensions/permissions.md) | Permissions and runtime prompts |
| [API reference](https://nana.areshk.dev/docs/extensions/api.md) | Every `nana` namespace and where it is available |
| [Events](https://nana.areshk.dev/docs/extensions/events.md) | Workspace events and kibble messages |
| [Tabs](https://nana.areshk.dev/docs/extensions/tabs.md) | Tab types, file openers, page data, and theme |
| [Panels](https://nana.areshk.dev/docs/extensions/panels.md) | Panels, popovers, and the sidebar |
| [Bar items](https://nana.areshk.dev/docs/extensions/bar-items.md) | Top bar and status bar items |
| [Commands](https://nana.areshk.dev/docs/extensions/commands.md) | Palette commands, shortcuts, and scripts |
| [Dialogs](https://nana.areshk.dev/docs/extensions/dialogs.md) | Dialogs, pickers, and modal web views |
| [Files](https://nana.areshk.dev/docs/extensions/files.md) | Reading and writing project files |
| [Git](https://nana.areshk.dev/docs/extensions/git.md) | Repository, branches, pull requests, and worktrees |
| [Localizations](https://nana.areshk.dev/docs/extensions/localizations.md) | Language packs |
| [Contributing](https://nana.areshk.dev/docs/extensions/contributing.md) | Publish to the marketplace |

## Where kibbles live

Installed kibbles live in the `extensions/<name>/` folder of Nana's
[profile folder](https://nana.areshk.dev/docs/features/server.md#files). Each is the build output, with
`package.json` at its root.

Manage them in **Settings → Kibbles**: **Installed** lists them with their
permissions, settings, and logs; **Browse** installs from the marketplace.
Kibbles start disabled after installing or loading.

## Security

- **Declared permissions.** Most API calls need a
  [permission](https://nana.areshk.dev/docs/extensions/permissions.md) in the manifest. Web requests, dialogs, and
  events need none.
- **Runtime prompts.** Running programs, typing into terminals, writing files or
  Git, web requests, and deleting projects ask the user first.
- **Declared events.** A kibble only receives the workspace events it
  lists in its manifest.
- **Own files only.** Pages load only from the kibble's own folder.
- **Verified installs.** Marketplace packages are checked against their listing
  before they are installed.