Change the start screen

New

The page you see when you start a session offers four ways in: understand a project, build a feature, research a topic, write something. Two of those four are aimed at code, and octo is not only for code — whoever is using it knows better than we do what their four things are. A lawyer’s are not a writer’s.

~/.octo/landing/ replaces them:

~/.octo/landing/
├── config.json
└── hero.webp        (optional — anything config.json points at)

{
  "title": "今天动哪块？",
  "subtitle": "Pick one, or just start typing.",
  "hero": { "image": "hero.webp", "height": 200 },
  "cards": [
    {
      "icon": "🔍",
      "title": "Take apart a post",
      "prompt": "Break down this post for me: the hook, the structure, why it worked."
    },
    {
      "icon": "ant-design:file-text-outlined",
      "title": "Review a contract",
      "prompt": "Read this contract and tell me what I should be worried about."
    }
  ],
  "apps": ["sketch"]
}

Reload the Web UI and it is there. Delete the directory and the built-in page comes back.

Field	Notes
title	The heading. Omit it to keep the built-in one, which is translated.
subtitle	The line under it. Same.
cards	Replaces all four. Up to 8; the grid follows the count and wraps past four.
cards[].title	The card’s label. Required.
cards[].prompt	What clicking it puts in the composer. Required.
cards[].icon	An emoji, or an icon name like ant-design:tool-outlined — anything without a : is drawn as text. Optional; prefer an emoji, see below.
hero	Fills the space above the mark. See below.
apps	Light App slugs, shown as shortcut chips under the cards. Up to 8. A slug you do not have installed is skipped.

About icons

An emoji always works. Anything without a : is drawn as text, so 🔍, ⚖️ or a single letter all render.

A name with a : is drawn as an icon — but octo ships its icons offline and never calls the Iconify API, so only the icons octo itself already uses are available. A name it does not carry renders as an empty space, with nothing to tell you why. Unless you are copying a name you have already seen in octo’s own UI, use an emoji.

The hero

The space above the octopus is the emptiest part of the page. hero fills it, from one of two sources — one or the other, not both:

"hero": { "image": "hero.webp", "height": 200 }

An image file sitting next to config.json. Animated GIF and WebP work, which is usually what “put an animation there” means. Servable types: .webp, .png, .jpg, .jpeg, .gif, .avif — SVG is deliberately excluded, since it carries script and these files are served from the app’s own origin.

"hero": { "app": "sketch", "height": 240 }

A Light App embedded as a frame — a clock, a board, a sketchpad you can draw on before you have even started a session. The whole of that machinery applies unchanged.

height is in pixels, clamped to 80–420: the hero shares the screen with the cards and the composer. Prefer the middle of that range (300–360) over the cap — a tall hero pushes the whole page past a short window, and since the page scrolls itself down to the composer, what gets cut off is the top of the hero.

Exactly one app. A landing page with several embedded apps is a dashboard, and every frame is something your first screen has to wait for. If both image and app are given, the image wins — a page that silently started running an app would be the worse surprise.

A hero app only appears when the browser is on the same machine as the server, the same rule mounted Light Apps follow. Over the network you get the plain landing page rather than a dead frame.

What clicking a card does

It loads the prompt into the composer without sending it. That is deliberate: the working directory and model pickers below still apply, and you can edit the text before you send. A starter is a starting point, not a shortcut past the controls.

So a good prompt reads like the first thing you would have typed — including the parts you would have had to say anyway (“ask me about the audience first”, “check the approach with me before implementing”).

The built-in four

Basing your own set on the defaults starts from knowing what they are. The built-in cards live in octo’s i18n rather than in a file you can open, so here they are — the Chinese UI shows its own translated wording:

Title	Prompt
Understand a project	Help me understand this project: what it does, how the code is organized, and where I should start reading.
Build a feature or tool	I want to build a small tool. Check the requirements and the approach with me first, then implement it.
Research a topic	Research a topic for me and write it up as a short brief, with the key takeaways and the sources they came from.
Write or organize	Help me write a document. Ask about the audience, the length and the main points first, then start drafting.

Copy a row into your own cards as a starting point — yours show exactly as written, in whatever language you write them. And if all you want is a hero or app shortcuts, leave cards out entirely: the built-in four stay.

Rules worth knowing

• It replaces, it does not merge. Your four are not the built-in four plus yours. A half-replaced set would be nobody’s.
• Whatever you write is what shows. The built-in cards are translated through octo’s i18n; yours are yours, in the language you wrote them in.
• A broken config costs you the overrides, not the page. Malformed JSON, a card with no prompt, a title of 400 characters — each is dropped or trimmed on its own, and you land on the built-in page rather than an error. It is a file you hand-edit; a stray comma is a likely state.

Also worth knowing

This changes the content. The look of the same page — background, accent, typeface — comes from your theme, so the two compose: see Write a theme.