# Project pack: Omni Tools @ 60bc64f

Facts about **Omni Tools** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Omni Tools is a self-hostable collection of small utilities for images, video, audio, text, lists, dates, numbers, JSON and PDF. Each tool runs in the browser, so your files and text are not sent to a server. It is useful as a personal toolbox you can host on your own network.

## Version and source
- Repository: https://github.com/iib0011/omni-tools
- Pinned commit: `60bc64f5a6974f3c802c5ec06cb3cf7f824485e1`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/iib0011/omni-tools/archive/60bc64f5a6974f3c802c5ec06cb3cf7f824485e1.zip
- Official docs: https://github.com/iib0011/omni-tools
- Live demo: https://omnitools.app. The official site runs the tools in your browser.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/iib0011/omni-tools bespoke-omni-tools
  cd bespoke-omni-tools
  git checkout --detach 60bc64f5a6974f3c802c5ec06cb3cf7f824485e1
  # Prepare development requirements and local configuration first.
  npm install
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name omni-tools --restart unless-stopped -p 8080:80 iib0011/omni-tools:latest
  # then open http://localhost:8080
  ```

- Needs: Docker for a trial, Node 22 for development
- Develop: `npm run dev`
- Test: `npm test`
- Check/lint: `npm run lint`
- Build: `npm run build`
- Stack: typescript (React, Vite, Material UI, FFmpeg.wasm). Difficulty for a non-developer with an AI: **easy**. A Vite and React app where each tool is a small folder with a component and metadata. Adding a tool is a copy-and-edit job.

## Customisation points (settings → extend → code)
- **tool-list** [settings]: Which tools your toolbox shows. → `The tool categories on the home page`
- **language** [extend]: Interface languages. → `public/locales/<language>`
- **new-tool** [code]: A new utility. → `src/pages/tools/<category>/<tool>`
- **theme** [code]: Colours, logo and layout. → `src/config and src/components`

## Must keep working
- Client-side processing. Don't send inputs to a server.
- The tool registry, since each tool registers itself there.
- Translation files used by the interface.

## Staying updatable
A tool is one self-contained folder. Add yours in a new folder so upgrading is a clean merge.

## Data, costs and safety
- Personal data: **no**. Stored in: Nothing is stored on a server. Tool inputs stay in the browser. Do not rely on it for confidential files unless you verify the tool runs locally.
- Tools like converters can use lots of memory for large files.
- Check each tool's description before using it on sensitive data.

---

# Customising Omni Tools

Omni Tools is a React app where each tool is a small folder, so adding a tool is the best first change.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Tools | src/pages/tools/<category>/<tool>/ |
| Shared components | src/components/ |
| Tool registry and categories | src/tools/ index files |
| Translations | public/locales/ |
| Styling | src/config/ and the theme in src/ |

## Use the gentlest change first

1. **Settings (no code):** none, as the tool list is built in.
2. **Extend:** translations and static hosting.
3. **Code:** new tools and themes.

## Recipes

- **New tool:** copy a similar tool folder, rename it, edit the component and meta file, and add it to its category index.
- **New language:** copy the `en` locale folder, translate it and add the language to the selector.

## Running and checking your changes

- `npm run dev` and use your new tool with typical and empty input.
- `npm run lint` and `npm test`.

## Pitfalls

- Keep each tool self-contained so it still works offline.
- Add locale keys for any new text.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/omni-tools/60bc64f/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/omni-tools/60bc64f/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/omni-tools/60bc64f/r2/SKILL.md)