Send code Get a working link

// title: Counter
// about: Counts your taps, for you only
export default async (req, gem) => {
  if (req.method === 'POST') {
    const n = (Number(await gem.store.get('n')) || 0) + 1;
    await gem.store.set('n', n);
    return {n};
  }
  return `<button onclick="gem.call('/', {}).then(r => this.textContent = r.n)">
    ${(await gem.store.get('n')) || 0}</button>`;
};

For AI assistants

Give this page to your coding assistant together with the job you want the app to do. For example: “Make a counter I can use at the gym. Save my count, let me reset it, and use Telegram’s colors.” The assistant should return one complete file and the steps to launch it.

1. Define the first useful version. Work from the person’s description. Establish who uses the app, what they do on its first screen and what needs to be saved. Add AI, search, scores or live interaction only when the job needs them. Ask for missing requirements together; if the brief is complete, build.
2. Write one complete file. Use JavaScript or TypeScript and stay within 4,000 Unicode characters, including newlines. Aim for 3,500 to leave room for fixes. First two lines: // title: Name and // about: one line on what it does; Gem reads the app’s name from the file. Export the handler export default (req, gem) => … that returns HTML (a string), a Response or an object; add export const live = gem => … only when the app needs rooms and real-time messages. Keep the code readable; shorten it only as needed to meet the size limit.
3. Use Gem for services and data. No imports, no fetch, no network: the only way out is gem.ask, gem.search, gem.store, gem.board, gem.kb and, in the browser, the injected window.gem library. Leaderboard scores are written by server code only (gem.board(name).add in export default or live); the page reads them with gem.top or gem.best.
4. Use the document route when it fits. If the app is built around a document (a guide, a manual, a menu, a course), tell the person they can send the document itself to @gembot after /newapp; for a design of your own, use gem.guide({...}) or gem.kb (see Knowledge apps).
5. Connect the page after it loads. Put page logic in the returned HTML inside onload = () => { … } because the library loads after your script. Use gem.theme colors so the app fits light and dark Telegram themes.
6. Check before sending: character count under 4,000; the two header lines present; export default present; no import, require or fetch in the server half; every gem.ask or gem.search call is worth a message from the person's plan; guests (gem.user.id === 0) handled or sent to Telegram with gem.guest(); leaderboard scores added only in server code; no telegram-web-app.js script tag (Gem provides Telegram.WebApp).
7. Deliver the whole file. Put it in one code block, ready to paste. Include these launch steps:

Your app is ready. To launch it:
1. Open https://t.me/gembot?start=newapp
2. Paste the whole code below as one message.
3. The bot replies with your app's link. Open it, and share it from the Share button inside the app.

```js
// title: …
// about: …
export default …
```

If Gem rejects the file or the app fails, fix the reported error and return the complete replacement file. Use Edit to update the existing app; a fresh /newapp request creates another one.

How it works

1. Open https://t.me/gembot?start=newapp (or send /newapp to @gembot). The next message you send is the code; the app's name is the // title: line inside it.
2. Gem stores it under a six-character slug and answers with the link https://t.me/gembot?startapp=<slug>.
3. Opening the link opens the Mini App at https://apps.gem.bot/<slug>: Gem's frame with the top bar (Build · title · Share), and your page inside it. Each request runs your handler in a fresh worker (10 seconds max). The HTML you return gets the gem client library and Gem's own Telegram.WebApp.
4. Use the gem APIs for external capabilities. Requests run on behalf of the person using the app and use that person’s allowance.

Your page is sandboxed

• The app page is isolated inside Gem’s frame. It cannot read the person’s notes, reminders or cards, or use another app’s data.
• Telegram.WebApp inside your page is Gem's stand-in: theme, safe areas, haptics, the Main, Back and Settings buttons, popups, links, shareMessage, QR scanning, downloadFile and CloudStorage (keys kept separate per app) work. Its initData is your app's pass: it opens your app only, for 24 hours, and is not the Telegram signature. The phone number, clipboard and write access are not available to apps.
• Gem supplies the Telegram interface, so omit telegram-web-app.js; its script tag is removed. Browser localStorage is available, isolated to your app and stored on the person’s device.
• Links to your own pages (/<slug>/…) load through Gem; other links open in Telegram's browser.

The handler

// title: Hello
// about: Greets whoever opens it
export default async (req, gem) => `<h1>Hi, ${gem.user.name || 'stranger'}</h1>`

req is a standard Request for https://apps.gem.bot/<slug>/<path> with method, query and body. Return an HTML string, a Response, or any object (sent as JSON).

gem.user is {id, name, language, premium}. It is the signed-in Telegram person when the request carries your app's pass (the client library does that for gem.call), otherwise a guest with id: 0. The pass itself never reaches your code.

Server verbs

When the person has used their message allowance, ask and search throw message limit reached — /buy in @gembot. Guests (id 0) can browse knowledge and search it by words. AI, personal storage, leaderboards and live connections require Telegram sign-in.

Live apps

Export live and your app also gets a long-lived worker. People connect to it over WebSocket, the library puts them into rooms, and your code reacts to events. This is how Gem-Pong pairs two players and moves the ball.

export const live = gem => {
  gem.rooms(2, {
    start(room) {                 // `size` players joined: room.players = [{id, name, index}]
      room.send({go: room.players.map(p => p.name)});
      room.t = setInterval(() => room.send({tick: Date.now()}), 33);
    },
    message(room, player, msg) {  // any JSON a player sends while in the room
      room.to(player, {echo: msg});
    },
    leave(room, player) {         // a player disconnected
      clearInterval(room.t); room.end();
    }
  });
};

• A player joins the queue by sending {join: 1} (the client library's channel.join()). Until the room fills, they get {wait: true, queue: n}. Matchmaking is public: the next people in line play together.
• {join: 1, solo: 1} (channel.join({solo: 1})) opens a room for that one person at once, with room.solo === true: this is how “Play against the computer” works, the app moves the other side itself in its tick.
• For a lobby of your own, use gem.hall({join(player), message(player, msg), leave(player)}) instead of rooms: everyone who connects is in the hall at once, you keep the queue and the matches yourself, gem.all(obj) sends to everyone in the hall, gem.to(player, obj) to one person, gem.players() lists who is connected. This is how the quiz “Интуиция” runs a 15-second lobby, matches of two to four and spectators on one server.
• room.send(obj) goes to everyone in the room, room.to(player, obj) to one person, room.end() frees the players so they can join again.
• gem.as(player).board(name).add(score, label) writes to the leaderboard as that player. Verbs in a live worker always need a player. gem.as(player).ask, search and kb.ask spend that player's message only right after their own message or join (within 60 seconds), at most six a minute.
• setInterval and setTimeout work. The worker keeps running between matches, stops after 2 minutes with nobody connected (and starts again when someone joins), and restarts when you send new code. A worker that does not respond for 15 seconds (an endless loop) is stopped, and its players are disconnected with code 4003.
• Only signed-in Telegram users can connect; the first frame carries your app's pass and the client library sends it for you. A connection may send up to 40 messages a second.

Knowledge apps

Turn a document into a browsable, searchable app. People can read the cards or ask questions and follow numbered citations back to the relevant source. This works for guides, manuals, menus, courses and price lists. For example: Mausfit, a nutrition guide made from one PDF.

• Start with a document. Send /newapp to @gembot, then a PDF, Markdown, JSON or text file instead of code. Gem organizes the content into sections and cards, names the app, adds four suggested questions and returns a link. Each document can contain up to 1,500 entries.
• Keep the content current. /myapps → Knowledge on any of your apps, then a file or pasted text. The replacement becomes the source for browsing, search and answers.
• Build your own interface. In the page or in server code: gem.kb.list({section, offset, limit}) gives the document in order with its sections; gem.kb.search(query, {limit, section}) finds by words and typos, and by meaning for signed-in people; gem.kb.ask(question, {history, style, strict}) answers from the 10 closest entries and returns {text, sources, cited}, where the text marks facts with [n]. style is your voice and rules in plain words; strict: false lets the answer add general knowledge, marked as such.
• Use the ready-made guide. gem.guide({...}) draws sections, cards, search, the ask tab with sources, a saved list and reading progress. Options: title, kicker, subtitle, accent, questions, style, strict, saved, cta, tabs; tabs adds your own tabs as {id, icon, label, render(el, api)}, the way Mausfit adds a calculator and a quiz.

// title: Our menu
// about: The menu, searchable, with answers
export default () => `<script>onload = () => gem.guide({
  title: 'Our menu', accent: '#8E1B2C',
  questions: ['What is vegan?', 'What is not spicy?'],
  style: 'Answer like a friendly waiter, in two sentences.'
})</script>`;
// Then: /myapps → Knowledge → send the menu as a PDF or text.

For richer cards, send JSON: [{section, title, body, url, tags, meta}]. meta.kind picks the card: product (with n, brand, shop, more), tip, recipe, place, combo (with meal), lead (a section's intro line) or cta; url becomes the card's button.

Client library

Gem injects window.gem into the HTML your handler returns. Use these helpers for requests, themes and interaction:

For games: input, canvas, effects

These helpers power Gem-Pong and support touch, mouse and keyboard input. Use them to keep the same interaction working across Telegram clients without separate controls for each device.

// A paddle you control, drawn every frame, sent to the server when it changes
const c = gem.canvas(), cur = gem.cursor(c.el, {min: .1, max: .9, axis: 'x'});
const ch = gem.live({message: d => tw.push(d)}), tw = gem.tween(33, ['ball']);
c.loop(dt => {
  ch.stream({x: cur.x});
  const s = tw.get(); if (!s) return;
  c.rect(cur.x * c.w - 40, c.h - 120, 80, 12, 6, gem.theme.button, 14)
   .dot(s.ball[0] * c.w, s.ball[1] * c.h, 8, gem.theme.accent, 16);
});

Limits

Cards and sharing

Gem gives each app a card with its title and description. Open launches it, Save keeps it in the person’s Gem, and Share sends the card to another chat. The app’s top-bar Share button uses the same card. You can also find it from any chat by typing @gembot app <slug>.

Your app's dashboard

Every app has a dashboard for its owner: https://apps.gem.bot/{slug}/db, or from Telegram with the deep link https://t.me/gembot?startapp={slug}-db. It shows people (all time, last 7 days, today), opens, live sessions, actions (model asks, web searches, app calls, saves, scores, shares), storage, every leaderboard's top five and a 14-day chart. Only the person who sent the code can open it.

HTTP endpoints

The client library wraps these HTTP endpoints. You can also call them from your app’s HTML. Use POST with JSON; authenticated calls carry initData, the app-scoped pass exposed as Telegram.WebApp.initData. The table marks endpoints that allow guest access.

Examples

A counter with storage

// title: Counter
// about: Counts your taps, for you only
export default async (req, gem) => {
  if (req.method === 'POST') {
    const n = (Number(await gem.store.get('n')) || 0) + 1;
    await gem.store.set('n', n);
    return {n};
  }
  return `<button onclick="gem.call('/', {}).then(r => this.textContent = r.n)">
    ${(await gem.store.get('n')) || 0}</button>`;
};

Ask the model

// title: Haiku
// about: A haiku about anything
export default async (req, gem) => {
  const topic = new URL(req.url).searchParams.get('q') || 'rain';
  return `<pre>${await gem.ask('Write a haiku about ' + topic)}</pre>
  <form><input name=q placeholder="topic"></form>`;
};

Showcase

Open these apps to see the APIs in use. They are maintained by Gem; your submitted code must still fit the 4,000-character limit.

Интуиция is a first-party multiplayer quiz: the model writes a question with ten options, the question reveals letter by letter, five stars each, first correct answer wins the round, a lobby with a 15-second countdown, matches of two to four with spectators, a leaderboard by best match.

Pocket Gem shows every verb on one screen in 3,985 characters: your name and visit count (gem.store), a question to the model (gem.ask), a web search (gem.search), private notes (store.list/set/del) and a five-second tap game with a leaderboard (gem.board), plus haptics and sounds from the client library.

Mausfit is a knowledge app made from one PDF: a nutrition guide with 14 sections and 134 cards with shop links, search, answers with sources, a shopping list, a calculator and a quiz scored on the server, built on gem.guide with two tabs of its own.

Gem-Pong is a full live game in 3,998 characters: play against a random person from the public queue or against the computer (a server-side paddle), ball physics on the server at 30 ticks per second, rounds that get faster, three misses and you are out, a round counts only if you moved, three idle rounds and you are out of the match, leaderboards by best round (rounds and solo), finger, mouse or arrow keys, glowing paddles and ball with a trail, sparks, flash and shake, sounds, music and haptics.

Manage your apps

Send /myapps to the bot to see your apps. Each has Open, Edit, Admin, Delete and Knowledge. Edit accepts replacement code as the next message and keeps the same link. Admin opens the owner dashboard. Delete asks for confirmation, then removes the app and its data. Knowledge takes a file or pasted text and makes it the app's knowledge.

Use these commands directly in @gembot; they are not listed in the general command menu.

Not yet in v0.1

• Server code cannot import packages from npm or URLs or make direct network requests. Use the documented Gem APIs.
• App code cannot run scheduled jobs, collect payments or accept file uploads. Personal storage is separate per person; leaderboards and knowledge provide shared data. Creators can upload documents through @gembot to build or update knowledge apps.
• Direct pass.io access is not available. It requires app-scoped tokens from Pass.