Texo Docs

What each part of Texo does, and how to use it.

Installing

Texo ships as one disk image that runs on both Apple silicon and Intel Macs. Liquid glass needs macOS 26 or later.

The app isn't signed with a paid Apple developer certificate yet. macOS will ask once before opening it.

How to

  1. Download the .dmg from the download page.
  2. Open it and drag Texo into Applications.
  3. Open Texo. macOS says it can't verify the developer. Close the message.
  4. Go to System Settings → Privacy & Security, scroll down, and click Open Anyway.
  5. From then on it opens normally.

Building from source

Build Texo yourself if you want to read the code before running it, try changes that haven't been released, or modify it. A build you make on your own Mac opens without the security prompt.

What you need

  • Apple's command line tools, for Git and the compiler: xcode-select --install
  • Node.js 20 or later, with npm

How to

  1. Get the code: git clone https://github.com/sjapanwala/texo, then cd texo.
  2. Run make dmg. It installs dependencies, builds the app and packages it for your Mac's chip.
  3. Run make open to open the release/ folder, then open Texo-0.1.0-arm64.dmg (or -x64 on Intel) and drag Texo into Applications.

Options

CommandResult
make dmgA disk image for this Mac's chip
make dmg ARCH=universalOne image for Apple silicon and Intel
make dmg ARCH=arm64 or ARCH=x64A specific chip
npm install then npm run devRuns Texo straight from the source, with hot reload, without packaging
make cleanRemoves build output

Builds are signed ad hoc by default. If you have an Apple Developer ID, make dmg SIGN=1 signs with it.

Your library

Your library is a folder: ~/Texo. Every note, database and drawing in it is a normal file. There is no database to export from and no proprietary format.

Other apps can open and edit the same files. When you switch back to Texo, it reads their changes.

How to

  1. Find anything: press ⌘K and type part of a title or a phrase from inside an item.
  2. Add a note: press ⌘N. It lands in the booklet you're looking at.
  3. Add something else: click the arrow beside Add Note to create a database, flow chart, drawing, notebook or shell note, import files, or start a recording.
  4. Bring in files: drag them onto the window, then choose a booklet.

Notes

Notes are Markdown files. What you see while writing is formatted. What gets saved is plain text you can read anywhere.

A note with a highlight, a callout and a table

What a note can hold

  • Headings, bold, italic, ==highlights==, links, quotes and dividers.
  • Code blocks with syntax colouring.
  • Tables, images and checklists. Checklists can nest bullets or numbered steps underneath.
  • Callouts: tip, note, info, warning, danger, success, question and quote.
  • Math, inline with $…$ or on its own line with $$…$$.

Every unchecked to-do in every note also appears in Home's To-dos widget. Tick it there and it's ticked in the note.

How to

  1. Insert anything: type / and pick a heading, list, callout, table, equation, code block, image, template or agent.
  2. Add a callout by hand: start a line with > [!tip] Title.
  3. Edit an equation: click it.
  4. Add an image: paste it, drop it in, or use /. It's saved to Attachments/ and linked by a relative path.
  5. Link two notes: add a normal Markdown link to the other note's file. Clicking it opens that note.
  6. Add emoji: type : and a few letters. The best match appears in grey. Tab accepts it, ↑ ↓ cycle through others.
  7. Fold a section: hover a heading and click the chevron, or press ⌘⌥[. ⌘⌥] unfolds. Folding changes the view only.
  8. Write without distractions: press ⇧⌘F for focus mode.

Templates

Four come built in: Meeting Notes, Project Brief, Daily Note and Lecture Notes. Any note you keep in a booklet named Templates becomes one too. {{date}}, {{time}}, {{weekday}} and {{title}} are filled in when you use it.

How to

  1. Click the arrow beside Add Note and choose From a template.
  2. Or, inside an open note, type / and the template's name to insert it at the cursor.

The status bar under each note shows word and character counts, reading time and whether it's saved. The outline beside the page lists its headings and can be hidden.

Kinds of items

Each kind is saved in an open format, so it outlives the app.

KindFileWhat it's for
Note.mdWriting
Shell note.shell.mdNotes beside a live terminal running your login shell
Notebook.ipynbPython cells run by a local kernel
Drawing.excalidrawFreehand sketches and diagrams
Flow chart.canvasProcesses and decisions
Database.csvAnything you'd track in rows

Notebooks need Python 3 with ipykernel installed: pip3 install ipykernel.

Databases

A database is a CSV file. Column types and views live in a small hidden file beside it, so the CSV stays clean for any spreadsheet app.

An assignments database
  • Column types: text, number, select, multi-select, date, checkbox, URL and more.
  • Views: table, board, gallery, calendar and chart.
  • Tools: filter, sort, search, and a calculation at the foot of each column.

How to

  1. Click the arrow beside Add Note and choose Database.
  2. Click a column header to rename it or change its type.
  3. Click Add a view beside the view tabs, then pick board, gallery, calendar or chart.
  4. Open any row as its own page to see every field at once.
  5. Already have a spreadsheet? Drop it in and turn it into a database.

Flow charts

Steps, decisions, start and end shapes, and sticky notes, joined by arrows. Each step can have its own colour.

A flow chart of a study process

How to

  1. Double-click the canvas to add a step.
  2. Drag from a step's dot to another step to connect them.
  3. Double-click an arrow to label it, for example "Yes" and "No" out of a decision.
  4. Use the toolbar to switch between step, decision, start or end, and note.

Files

PDFs, Word and Pages documents, slides, spreadsheets, images, audio, video and plain text open inside Texo. Previews use tools built into macOS, so there is nothing extra to install.

A Word document can become an editable note. A spreadsheet can become a database.

Booklets

A booklet is a folder. Make one per class, project or team, and nest them as deep as you like, for example School/Math.

Each booklet can have an SF Symbol and a colour. The colour shows wherever the booklet appears.

How to

  1. Click the folder button beside Booklets in the sidebar to create one.
  2. Right-click a booklet and choose Change icon & colour…. Pick any symbol, one of ten colours, or a custom colour.
  3. Rename, move, reveal on your Mac, or move to the Trash from the same menu.
  4. Click a booklet to open its page, which lists everything inside it, including sub-booklets.

Home

The first page you see. You choose what's on it and how big each piece is.

Home with an activity heatmap, recent items and an automation
WidgetWhat it shows
Recently openedWhere you left off
To-dosUnchecked items from every note
TimerPomodoro, countdown or stopwatch
Quick captureWrites into an Inbox note
Pinned itemAny item, with a live preview
Image, Text cardA picture or a sticky note
Agent automationIts schedule, last run and a Run now button
ActivityA year of edits as a heatmap, with streaks. Needs GitHub sync.

How to

  1. Click + Widget and pick one.
  2. Click Customize to drag widgets around and resize them. Click Done when finished.

Building an agent

An agent is an assistant with one job. You write the job in plain words, choose which AI it runs on, and decide what it's allowed to touch.

Editing an agent

Templates cover common jobs: Study Coach, Librarian, Planner, Researcher, Editor and more. Each one is a starting point you can rewrite.

Providers

Claude, ChatGPT, Gemini, Groq, or Ollama running on your Mac. Ollama is free and keeps everything local. The others need an API key from the provider.

Two dials set each agent's behaviour. Brainpower picks a more or less capable model. Budget caps how much one task may spend. You can also pin a specific model.

How to

  1. Open Settings → AI providers and add a key, or the address of your Ollama server.
  2. In the sidebar, click + next to Agents.
  3. Pick a template, or skip it to start blank.
  4. Give the agent a name and a face: shape, colour, eyes, mouth and extras.
  5. Write its job. Be specific: "Turn my lecture notes into flashcards and quiz me" works better than "Help me study".
  6. Choose a provider, set the dials, and switch off any abilities it doesn't need.
  7. Click Create agent. A chat with it opens.

Where agents work

Agents can see what you're working on. They know which item is open, what you've selected, a notebook's active cell and its output, and a terminal's recent output.

The agent wheel inside a note

Inside a note

Press ⌘J and a wheel of your agents opens at the cursor. Pick one, then an action:

  • Run: do its job on this note now, with no prompt. A Study Coach makes flashcards. An Editor tidies the writing.
  • Ask: a question about the paragraph you're in.
  • Write: continue from the cursor.
  • Improve: rework the selected text.
  • Find links: suggest related notes.

Typing / and an agent's name opens it on Ask.

In a chat

Each step the agent takes appears as it happens: what it searched, what it read, what it changed. Under every task you see the tokens used, an estimated price, the number of steps and how long it took.

A chat with an agent, step by step

If a request is unclear, the agent asks, with answers to pick from. You can speak a message with the mic button and have replies read aloud in one of your Mac's voices.

How to

  1. Start a chat: click an agent in the sidebar.
  2. Find an old chat: open the chats panel beside the conversation. Chats are searchable and grouped by day.
  3. Keep a chat on screen: pop it out into its own small window. It can float above other apps while the agent keeps working in the main window.

Automations

An automation is a saved task that an agent runs on its own. It can run on a schedule, every few hours, when items are added or changed in a booklet, or when Texo opens.

Examples: "Every Friday at 17:00, write a weekly summary of what I changed." "When a new note lands in School, make flashcards for it."

Automations always send a macOS notification when they finish. Big changes arrive as suggestions instead of being written straight in.

How to

  1. On Home, click + Widget and choose Agent automation.
  2. Name it, pick the agent, and write the task as you'd say it.
  3. Pick when it runs.
  4. Save. The widget shows the next run. Run now runs it immediately.
  5. Or just ask an agent: "remind me every Monday to plan the week". It can schedule tasks for itself.

Abilities

Every ability can be switched off per agent. A switched-off ability removes those tools from the agent entirely. It can't use what it doesn't have.

AbilityWhat it allows
ReadAlways on. Search and read every item, PDFs page by page, slides, transcripts, images, backlinks, tags and version history.
WriteCreate and edit items. Flow charts, drawings and notebooks are changed one operation at a time ("add a step after X") rather than rewritten.
OrganizeRename and move items. Create and rename booklets.
DatabasesAdd, update and delete rows. Add, rename and retype columns. Sort and filter views.
DeleteMove things to the Trash. Always asks first.
WebSearch the web and read pages. DuckDuckGo works without a key. Google and Brave need one, set in Settings → AI providers → Web search.
Run codeRun notebook cells, and shell commands on your Mac. Every shell command asks first.
Control the appOpen items, pin them to Home, switch the theme, send you notifications, schedule tasks.
GitHubPropose changes for review, restore old versions, recover deleted items, sync, publish the website.

More abilities are on the way.

Memory and cost

Memory

Tell an agent something worth keeping, like an exam date or how you want questions asked, and it saves it for future chats. Each fact is a short line you can read.

How to

  1. Hover the agent in the sidebar, click ⋯, then Edit agent.
  2. Scroll to Memory to read, edit or clear what it remembers.

Cost

Every task shows its tokens and an estimated price, based on the provider's list prices. Settings → AI providers → Usage & cost breaks down this month and the last 30 days by agent and by model. Local models through Ollama cost nothing.

Usage and cost by agent and model

Agents are built to spend little. Claude reuses each chat's instructions from its cache, which costs about a tenth of the normal price. Long items are read in pages, databases are queried instead of read whole, and old tool results are dropped from long chats.

Studio

A research project built on your own sources. The agent answers only from what you've added, and cites it.

  • Sources: notes, PDFs, slides, recordings with transcripts, web pages or pasted text.
  • Ask: answers come with numbered citations. Click one to open the source.
  • Make: an audio overview with two hosts, a study guide, briefing, FAQ, timeline, mind map, flashcards or a quiz. Each is saved as an item with what it cost.

Small sets of sources are handed to the agent whole. Large sets are searched passage by passage, which keeps the cost down.

How to

  1. Open Studio in the sidebar and click New project.
  2. Add sources, or start from a booklet so everything in it becomes a source.
  3. Untick any source you want left out.
  4. Ask a question, or pick something to make.

Recording

Record a lecture or meeting, then transcribe it with Groq Whisper, OpenAI Whisper or Gemini. Gemini also labels who is speaking. The transcript is kept with the recording.

How to

  1. Click the arrow beside Add Note and choose Record audio.
  2. Stop when you're done, then transcribe. Settings → Recording can do this automatically.
  3. Click any line of the transcript to jump to that moment.
  4. Ask an agent to turn the transcript into notes.

Sync

Texo syncs your library through a GitHub repository in your own account. It's free, and the repository can be private.

Sync settings, signed in to GitHub

Texo commits and pulls at launch, about 20 seconds after you edit, every 5 minutes, when your Mac wakes, and before quitting.

Conflicts

  • Same note edited on two Macs: this Mac's version stays. The other one is saved beside it as "Note (conflicted copy 2026-11-16 09.30)", and you get a notification.
  • Edited on one Mac, deleted on the other: the edit wins.
  • Files over 95 MB stay on the Mac they were made on. GitHub refuses files over 100 MB.

How to

  1. Install Git if you don't have it: run xcode-select --install in Terminal.
  2. Open Settings → Sync and click Sign in with GitHub, or paste a personal access token.
  3. Create a new repository, or pick an existing one. Picking an existing one is how a second Mac joins.
  4. The Signed in as bar under the logo shows the sync status. Its menu opens the repository, syncs now, and opens Recently deleted.

Version history

With sync on, every synced version of every item is kept. Each version is labelled: edited, synced from another Mac, restored, accepted a suggestion, or the name of whoever changed it.

A note's version history with a diff

Restoring never overwrites history. The old version comes back as a new version, so a restore can be undone too.

How to

  1. Open an item and click the clock button in its header.
  2. Pick a version. Changes since shows what's different in red and green. Whole version shows the full text as it was.
  3. Click Restore this version.
  4. To get back a deleted item, open Settings → Sync → Recently deleted…. It lists items deleted on any of your Macs, with a preview.

Edit, Suggest and View

Every item has a mode switch in its header. The mode is remembered per item, per Mac.

  • Editing: changes go straight into the item.
  • Suggesting: changes are saved on the item's own suggestion branch. The item itself is untouched. In a note, added text is underlined in green and removed text stays visible, underlined in red.
  • Viewing: read-only. You can still scroll, select, copy, pan and zoom.

How to

  1. Click the mode button in the item's header (it reads Editing by default) and choose a mode.
  2. In Suggesting, hover a change to undo it, or use Discard all.
  3. Your suggestion syncs to your other Macs, where it can be accepted or rejected in Editing mode.

Suggestions

Changes proposed by someone else, reviewed right on the page. They come from four places: pull requests on your repository, branches pushed by collaborators, agent proposals, and your own Suggesting mode.

Suggested edits shown inline

Accepting keeps your own edits. Texo merges the suggestion with what's on your page now, line by line, and only asks when you both changed the same lines.

When every change is decided, a pull request is closed with a thank-you comment and an agent's branch is deleted.

How to

  1. A bar above the note says who suggested what. The bell shows new suggestions too.
  2. Hover a change to accept or reject just that one.
  3. Or use Accept all or Reject all. With several suggestions, ‹ › flips between them.
  4. For databases, drawings and other items, open the suggestions panel from the header to see a line-by-line diff.

Websites

One booklet becomes a website on GitHub Pages. Each note is a page. A note called index, Home or README is the front page, and sub-booklets become sections of the menu.

The website page with a live preview

Headings, lists, tables, callouts, highlights, math, images and links between notes all render. Databases become tables.

The site is published from its own public repository, so the rest of your library stays private.

Page settings

A short header at the top of a note controls its page:

---
title: About me
description: Shown in search results
order: 1        # position in the menu
draft: true     # leave it off the site
hidden: true    # on the site, not in the menu
---

How to

  1. Open Website in the sidebar and choose a booklet.
  2. Set a title, tagline and footer. Pick a theme: Paper, Minimal, Docs or Midnight, or No theme with your own CSS.
  3. Watch the live preview, then click Publish website.
  4. The address is you.github.io/site-name. For a custom domain, Texo shows the exact DNS records to add. HTTPS turns on by itself.
  5. Republish with one click, or let it republish after each sync that changed the booklet. Unpublish takes the site down.

Notifications

The bell next to Settings collects sync conflicts and failures, new suggestions, website builds, and finished agent tasks and automations. Click one to go straight to it. When Texo isn't in front, the important ones also show as macOS notifications.

Agent tasks that take longer than 20 seconds notify you when they finish.

Appearance

On macOS 26 and later, the window sits on real liquid glass. The slider runs from solid panels to fully clear.

A note in dark mode on liquid glass

How to

  1. Open Settings → Appearance.
  2. Choose System, Light or Dark.
  3. Drag Liquid glass between Solid and Clear.
  4. Pick a Tint colour and set its strength, or leave it clear.
  5. Turn on Bold sidebar icons or give the icons a colour. Reduced motion is here too.
  6. Settings → Editor sets the font (sans, serif or mono), text size and page width.

Shortcuts

⌘NNew note in the current booklet
⌘KFind a note
⌘JSummon an agent in a note
⌘\Show or hide the sidebar
⇧⌘FFocus mode
/Insert a block, template or agent
: then TabInsert an emoji by shortcode
⌘⌥[ / ⌘⌥]Fold or unfold the section under a heading

Privacy and security

There is no Texo server. Your notes stay on your Mac unless you turn on sync. Then they go to your own repository and nowhere else.

  • Keys: AI provider keys and your GitHub token are encrypted with the macOS Keychain, stored outside your library, and never exposed to the app's pages. Git receives the token through its environment, so it never appears in a command line or in .git/config.
  • Your email: commits use GitHub's private no-reply address.
  • GitHub access: signing in asks for GitHub's repo permission, which covers every repository you can push to. For narrower access, sign in with a fine-grained personal access token limited to your notes repository.
  • Agents: they ask before moving anything to the Trash, overwriting a whole item, restoring an old version or running a shell command. Switch off any ability an agent doesn't need.
  • Fully local: run agents on Ollama and nothing leaves your Mac.

About

Texo exists because the useful parts of note apps keep moving behind subscriptions. Sync across devices, version history and AI help are often locked to a monthly plan. Students, who use these tools every day, are the people least able to pay for all of them.

Texo includes all of it, free. There are no tiers, no trial and no account with us.

What it costs to run

  • The app: nothing.
  • Sync and history: nothing. They use a repository in your own GitHub account.
  • Websites: nothing. GitHub Pages hosts them.
  • Agents: whatever your AI provider charges for the tokens used, usually a few cents a task. Every task shows its cost. With Ollama on your Mac, it's free.

Open source

The full source is on GitHub under the MIT license. You can read it, run it, change it and share your changes. If Texo ever stopped being maintained, your notes would still be plain files, and the code would still be there for anyone to pick up.

Contributing

Anyone can contribute. Bug reports, feature ideas, documentation fixes and code are all welcome, and you don't need to ask before starting.

Report a bug or suggest a feature

How to

  1. Open the issues page and check whether it's already there.
  2. Open a new issue. For a bug, include your macOS version, what you did, what you expected and what happened instead. A screenshot helps.

Run Texo from source

You need macOS and Node.js 20 or later. Git is needed for sync, and Python 3 with ipykernel for notebooks.

git clone https://github.com/sjapanwala/texo
cd texo
npm install        # also rebuilds the terminal module for Electron
npm run dev        # opens the app with hot reload
CommandWhat it does
npm run devRuns the app with hot reload
npm run typecheckChecks the TypeScript
npm run buildTypechecks and bundles the app into dist/
npm run distBuilds a macOS .dmg
npm run screenshotsRetakes the screenshots from a demo library. Your own notes are never touched.

Where things live

  • src/: the interface, in React and TypeScript.
  • electron/: everything that touches your Mac: files, sync, history, suggestions, websites and agents.
  • scripts/: build, packaging and screenshot tools.
  • docs/: this website.

Send a change

How to

  1. Fork the repository on GitHub and create a branch for your change.
  2. Make the change. Keep it focused on one thing.
  3. Run npm run typecheck and try it in npm run dev.
  4. Open a pull request against main. Say what changed and why. For anything visual, add a screenshot.