# Project pack: Glance @ 8958aa8

Facts about **Glance** 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.

> Glance is a self-hosted dashboard that puts everything you check each day on one fast page: RSS feeds, weather, Reddit, YouTube, stock prices, calendars, server stats and more. It is a single small program configured with one YAML file, and looks good on desktop and phone.

## Version and source
- Repository: https://github.com/glanceapp/glance
- Pinned commit: `8958aa827275cf81c01f3d5afe7180354a200cc6`. 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/glanceapp/glance/archive/8958aa827275cf81c01f3d5afe7180354a200cc6.zip
- Official docs: https://github.com/glanceapp/glance/blob/main/docs/configuration.md
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

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

  ```sh
  git clone https://github.com/glanceapp/glance bespoke-glance
  cd bespoke-glance
  git checkout --detach 8958aa827275cf81c01f3d5afe7180354a200cc6
  # Prepare development requirements and local configuration first.
  go run . --config docs/glance.yml
  ```

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
  mkdir glance && cd glance
  curl -o glance.yml https://raw.githubusercontent.com/glanceapp/glance/main/docs/glance.yml
  docker run -d --name glance -p 8080:8080 -v ./glance.yml:/app/config/glance.yml glanceapp/glance
  # then open http://localhost:8080
  ```

- Needs: Docker for a trial, Go 1.23+ for development
- Develop: `go run . --config docs/glance.yml`
- Test: `go test ./...`
- Stack: go, html, javascript (Go standard library, HTML templates, vanilla JavaScript). Difficulty for a non-developer with an AI: **easy**. A single Go binary with templates and widgets as separate files. You rarely need code: widgets and a custom-api widget cover most needs.

## Customisation points (settings → extend → code)
- **pages-and-columns** [settings]: What appears on which page, in what order. → `glance.yml (pages, columns, widgets)`
- **widgets** [settings]: Your feeds, city, stocks and lists. → `glance.yml widget options (rss, weather, markets, calendar and more)`
- **themes** [settings]: Colours, light and dark. → `glance.yml theme section and docs/themes.md`
- **custom-api-widget** [extend]: Show data from any JSON API in your own template. → `docs/custom-api.md`
- **extension-widget** [extend]: Embed HTML from your own small service. → `docs/extensions.md`
- **go-widgets** [code]: New widget types. → `internal/glance`

## Must keep working
- Configuration compatibility, since users hand-write glance.yml.
- Server-side fetching limits and caching of external sources.
- Security of the custom API widget templates.

## Staying updatable
Everything you need is a YAML file. If you add a widget in Go, keep it in its own file.

## Data, costs and safety
- Personal data: **no**. Stored in: A YAML configuration file. Nothing else is stored. The config may include API keys for widgets. Keep it out of Git if so.
- Service: Weather, markets and feed sources (optional, free): Content for the widgets.
- Keep it on your home network or behind a login. It has no login of its own.
- API keys in glance.yml are secrets. Keep them out of Git and chats.

---

# Customising Glance

Glance is configured in YAML. Almost every change is an edit to glance.yml, so start there.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Your configuration | glance.yml |
| Widgets and pages (Go) | internal/glance/ |
| HTML templates | internal/glance/templates/ |
| Static files | internal/glance/static/ |
| Documentation | docs/ |

## Use the gentlest change first

1. **Settings (no code):** pages, columns, widgets and theme in glance.yml.
2. **Extend:** the custom-api and extension widgets.
3. **Code:** new Go widgets.

## Recipes

- **Show data from a JSON API:** add a `custom-api` widget with the URL and a template that formats the fields.
- **New widget:** copy a simple widget file in `internal/glance`, add a template, and register its type.

## Running and checking your changes

- `go test ./...` and `go run . --config glance.yml`, then reload the page.
- Check the page on a phone-sized window.

## Pitfalls

- YAML indentation errors prevent startup. Validate after each edit.
- Don't hard-code secrets. Use environment variable substitution.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/glance/8958aa8/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/glance/8958aa8/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/glance/8958aa8/r2/SKILL.md)