README.md

README.md

1. # Cortex
3. A native desktop client for language models that shows what every reply
4. costs. Tauri v2 (a Rust shell) and React, on DeepInfra's hosted models or any
5. model server you run yourself.
7. ![Cortex in light mode: a sidebar of chats with the cost of each, and a conversation about a backup script with the tokens and cost under the reply](docs/screenshots/main-light.png)
9. ## Quick start
11. Needs Rust (stable) and Node 22. On Linux, also the WebKitGTK development
12. libraries that `.github/workflows/ci.yml` installs.
14. ```bash
15. npm ci
16. npx vite build # first: the Rust build embeds the built interface
17. cargo test --workspace # core logic, the provider against the stand-in, whole turns
18. npm test # Vitest: formatting, markdown safety, the store, the app renders
19. npm run typecheck # tsc
20. npm run test:ui # Playwright: the interface in Chromium, on sample data
21. npm run tauri dev # the app, with hot reload
22. ```
24. The end-to-end run drives the real app over WebDriver on Linux. It needs
25. `webkit2gtk-driver`, `xvfb`, `dbus-x11` and `cargo install tauri-driver`, and a
26. debug build with the `e2e` feature first:
28. ```bash
29. npx tauri build --debug --no-bundle --features e2e
30. scripts/e2e-linux.sh
31. ```
33. CI also checks formatting and lints:
35. ```bash
36. cargo fmt --all --check
37. cargo clippy --workspace --all-targets -- -D warnings
38. npm run format:check # Prettier over src/ and e2e/
39. ```
41. ## Why it exists
43. Hosted chat apps charge a flat monthly fee whether you ask one question or a
44. thousand. Paying per token through an inference provider is usually far
45. cheaper, but only if you can see what you are spending. Cortex puts the price
46. of every reply in front of you: tokens in and out and the dollar cost under
47. each answer, a running total per conversation, the month so far against a
48. budget, and an estimate of what a prompt will cost before you send it.
50. ## How it is built
52. The logic lives in `crates/cortex-core`, a plain Rust library: the provider
53. client and its streaming parser, pricing and cost, SQLite storage with
54. full-text search, attachments and export. `src-tauri` holds the commands, the
55. windows, the tray and the shortcut. The React interface talks to it through
56. one typed interface, whose TypeScript types are generated from the Rust
57. structs. More in [docs/architecture.md](docs/architecture.md).
59. ```
60. crates/cortex-core/ providers, streaming, pricing, cost, storage, export
61. crates/standin/ the test stand-in for DeepInfra and local servers
62. src-tauri/ the desktop shell: commands, windows, tray, shortcut
63. src/ the React interface (main window and quick prompt)
64. e2e/ Playwright (interface) and WebDriver (real app) tests
65. docs/ architecture, cost accounting, the Mac checklist
66. ```
68. ## What it does
70. - **Streaming chat** with any chat model on DeepInfra, or on a local server
71. (Ollama, LM Studio, llama.cpp: anything OpenAI-compatible). Stop a reply at
72. any point; what arrived is kept.
73. - **A cost meter everywhere.** Live per-model prices from DeepInfra, stored
74. with each reply so history never changes. Estimates are labeled "est.".
75. Local models cost nothing. See [how cost is counted](docs/cost-accounting.md).
76. - **A model picker with prices:** search, filter by vision, reasoning,
77. favorites or local, and see input and output price per million tokens and
78. the context size before you choose.
79. - **A quick prompt.** Cmd+Shift+Space anywhere opens a small frosted prompt
80. over whatever you are doing. Ask, read, press Esc. Cmd+Enter moves the
81. conversation into the main window.
82. - **Presets:** saved system prompts (with an optional model and temperature),
83. applied to a chat in one click.
84. - **Search** across every chat (full-text, as you type).
85. - **Export to an Obsidian vault:** a conversation as Markdown with
86. frontmatter (models, tokens, cost), images copied beside it.
87. - **Images and files:** paste or drop an image for a vision model (it is
88. downscaled first, since vision models bill by size), or a text file to read
89. as context.
90. - **macOS window materials:** frosted panels over native vibrancy, light and
91. dark, with a choice of material and panel tint, and a solid mode for when
92. transparency gets in the way.
93. - **Menu bar:** this month's spend, a new chat or the quick prompt, from
94. anywhere.
96. ## Screenshots
98. ![Cortex in dark mode, reading a chart of two pricing plans with a vision model](docs/screenshots/main-dark.png)
100. ![The model picker: every chat model with its input and output price per million tokens and its context size](docs/screenshots/model-picker.png)
102. ![Usage: spend this month by model and by day](docs/screenshots/usage.png)
104. ![The quick prompt with an answer and its cost](docs/screenshots/quick-prompt.png)
106. *Screenshots are the interface on its built-in sample data (every chat in them
107. is invented), shown over the backdrop the page paints when there is no native
108. vibrancy. On a Mac the panels sit on the frosted desktop instead.*
110. ## Privacy
112. - Chats, attachments and settings live in one SQLite file on your computer.
113. - API keys live in the macOS Keychain, never in the database or a file. The
114. interface can set or remove a key but never read one back. A key is checked
115. with the provider before it is stored, so a mistyped one is caught at once.
116. - The only network traffic is to the provider you chose, from the Rust side.
117. The webview itself cannot reach the network (its content security policy
118. allows none).
119. - No telemetry, no accounts, no update pings. With a local model, nothing
120. leaves the machine at all.
122. ## Install
124. Build from source: after the Quick start, `npm run tauri build` makes a
125. release build (the `.app` and a `.dmg` on macOS). The build is ad-hoc signed,
126. not notarized, so macOS asks once: open System Settings, Privacy & Security,
127. and choose "Open Anyway". Then:
129. 1. Settings, DeepInfra: paste your API key (from deepinfra.com, Dashboard, API Keys).
130. 2. Optionally add a local server under Local servers (Ollama is
131. `http://localhost:11434/v1`).
132. 3. Set a monthly budget if you want the warnings.
134. `npm run dev` serves the interface alone in a browser, on sample data.
136. ## Tests
138. The Rust tests run every provider path against `crates/standin`, a small
139. OpenAI-compatible server whose behavior is picked by model id: streaming with
140. usage, no usage, cached tokens, reasoning, images, errors before and during a
141. stream, and a slow reply for testing Stop (which checks that the server sees
142. the connection close). The Playwright run covers two window sizes in both
143. themes, the main flows, and an axe check for contrast and labels. The
144. end-to-end run starts the actual Tauri binary under a virtual display, points
145. it at the stand-in, and sends a message, stops one, searches, and exports a
146. note.
148. What needs a real key and a Mac (live prices, DeepInfra's usage reporting,
149. vibrancy, the Keychain, the global shortcut) is a five-minute checklist in
150. [docs/verify-on-mac.md](docs/verify-on-mac.md).
152. ## Keyboard
154. | Keys | Does |
155. |---|---|
156. | Cmd+Shift+Space | Quick prompt, from anywhere (changeable) |
157. | Cmd+N | New chat |
158. | Cmd+K | Search chats |
159. | Cmd+, | Settings |
160. | Enter / Shift+Enter | Send / new line |
161. | Esc | Stop the reply; close a panel |
162. | Cmd+Enter (quick prompt) | Continue in the main window |
164. ## Limitations
166. - No tool calling or agents: Cortex is for talking to a model, on purpose.
167. - macOS is the target. Linux builds and is tested (without vibrancy); Windows
168. is not built.
169. - The quick prompt may not appear over full-screen apps on macOS.
170. - Token estimates for local servers are approximate, and marked as such.
171. - Prices come from DeepInfra's public model list, which is an extension to the
172. OpenAI format rather than a documented contract; the dated offline copy is
173. the fallback.
175. ## License
177. MIT.