SEP Reader is a Linux desktop application for reading, studying, annotating, and exporting articles from the Stanford Encyclopedia of Philosophy (SEP). All made by AI
The project is designed around a simple idea: long-form philosophical reading benefits from a dedicated environment that combines focused reading, persistent annotations, navigation, and portable notes without turning the reading experience into a general-purpose web browser.
Project status: Early beta.
SEP Reader is already usable for everyday reading and annotation, but its interface, storage model, packaging, and internal architecture may change during development.
Stanford Encyclopedia of Philosophy articles are often long, highly structured, bibliographically rich, and read across multiple sessions. A normal browser is excellent for accessing SEP, but it is not specifically designed as a philosophical study environment.
SEP Reader adds a study layer around SEP.
It currently allows users to:
- browse SEP without leaving the application;
- search the Stanford Encyclopedia of Philosophy;
- switch to a distraction-reduced reading mode;
- change reading font size and content width;
- remember reading position for individual articles;
- see approximate reading progress;
- save favorite articles;
- access recently opened entries;
- navigate through an article's table of contents;
- search within the currently open article;
- create persistent Markdown notes for each article;
- preview supported Markdown formatting;
- create persistent text highlights;
- assign colors to highlights;
- preserve the section in which a highlight was created;
- jump from the highlights panel back to the original passage;
- insert a highlight into the article's notes as a Markdown blockquote;
- export notes and highlights to a portable Markdown file.
The long-term goal is to develop SEP Reader from a specialized SEP reader into a broader local-first environment for philosophical and academic research.
SEP Reader uses the Stanford Encyclopedia of Philosophy as its primary content source and allows SEP pages to be navigated inside the application.
The top bar provides standard navigation controls:
- Back --- return to the previously visited page.
- Forward --- move forward after navigating back.
- Home --- return to SEP Reader's native home screen.
- SEP search --- enter a query in the main search field and search the Stanford Encyclopedia of Philosophy.
Links inside SEP entries can be followed without leaving the application.
SEP Reader has its own home screen rather than simply using SEP's website as its starting page.
The home screen is intended to act as the entry point to the user's reading activity and currently provides access to previously visited material and reading continuation.
A future goal is to evolve this screen into a full personal research library.
SEP Reader keeps track of recently opened articles and makes it possible to return to ongoing reading sessions.
This is particularly useful for long SEP entries that may be read over several days or sessions.
Reading continuation works together with per-article reading-position restoration.
SEP Reader records reading progress for individual SEP entries.
When a previously read article is reopened, the application attempts to restore the approximate scroll position at which the user stopped reading.
Reading position is stored locally and associated with the article.
A small percentage indicator is also displayed near the bottom of the reading area.
For example:
22%
This provides a lightweight indication of how far the reader has progressed through the article.
SEP entries can be added to a persistent Favorites list.
The star button in the header can:
- add the current SEP entry to Favorites;
- remove it if it is already saved.
Favorites are displayed in the left sidebar and remain available after restarting the application.
The favorite action is enabled only for supported SEP entry URLs.
SEP Reader automatically maintains a list of recently opened articles.
Recent entries are shown in the Recents section of the left sidebar.
The current implementation stores up to 20 recent entries.
This acts as a lightweight reading history and provides a quick way to return to recently consulted material.
The left sidebar currently contains:
- Favorites;
- Recents.
It can be hidden when more horizontal space is needed for reading.
The goal is to keep navigation available without forcing it to remain visible during focused reading.
SEP Reader includes a dedicated Reading Mode for SEP entries.
Reading Mode modifies the presentation of the article to reduce secondary page elements and focus attention on the main text.
It:
- simplifies the page presentation;
- centers the reading content;
- constrains text width;
- allows font-size adjustment;
- remains compatible with notes, highlights, and the article table of contents.
The reader can switch between the original web presentation and Reading Mode at any time.
When Reading Mode is active, additional reading controls are available.
Decreases the reading font size.
Increases the reading font size.
The current implementation constrains font size to a range intended to preserve readability.
The reading column can use three predefined widths:
- Narrow
- Medium
- Wide
Restores the default reader settings.
Reader preferences are persisted locally between sessions.
The table-of-contents control exposes the internal structure of the current SEP entry.
The table of contents is generated from the article's headings and can be used to navigate between sections.
It is designed to remain usable in Reading Mode.
Scrolling over the table of contents is isolated from the article itself so that browsing the section list does not unintentionally scroll the main text.
SEP Reader provides a search function for the currently open article in addition to SEP's global search.
Open it with:
Ctrl+F
As the query is entered, SEP Reader:
- searches the article text;
- visually marks matches;
- scrolls to the active match;
- displays the current match and total number of matches.
For example:
3/12
This means that the third of twelve matches is currently active.
The search bar includes controls for moving to the previous or next result.
Closing Find in Article removes its temporary search marks without affecting persistent study highlights.
Each SEP entry can have its own note.
Notes are stored locally as Markdown files and associated with the corresponding article.
The notes panel appears on the right side of the application.
Its width can be adjusted, and SEP Reader remembers the chosen panel width between sessions.
Notes are automatically saved while the user works.
A manual save action is therefore not required after every change.
The panel is intended to behave like a persistent reading notebook attached to the current article.
Notes use Markdown, keeping the user's writing in a portable plain-text format.
The editor toolbar currently provides shortcuts for several common Markdown structures.
**text***text*The H control inserts a Markdown heading.
A level-one heading may be used naturally inside SEP Reader. During export, note headings are shifted down one level so that level one remains available for the exported document's top-level structure.
- item`code`> Quoted passageThe notes panel can switch between:
- Editing
- Preview
The current preview renderer supports the Markdown structures used by the editor, including:
- headings;
- bullet lists;
- bold;
- italic;
- inline code;
- blockquotes.
Markdown support is intentionally still limited in the beta and is expected to expand.
Text from SEP articles can be turned into persistent highlights.
Highlights remain stored after the application is closed and are restored when the corresponding entry is reopened.
Highlight data is associated with the article's path.
SEP Reader currently provides two highlighting workflows.
When automatic highlighting is disabled, text behaves like a normal browser selection.
The native WebKit context menu exposes a:
Highlight
action for selected text.
The highlight control in the header acts as a toggle. When enabled, selecting text automatically creates a persistent highlight. This is useful for intensive reading sessions in which many passages are being marked. When disabled, text selection returns to normal behavior.
A stored highlight can be removed by clicking the highlighted passage in the article.
The corresponding persistent highlight data is updated so that the highlight does not return after reopening the article.
Highlights currently support four colors:
- yellow;
- green;
- blue;
- pink.
The colors deliberately have no fixed semantic meaning. Readers can create their own annotation system.
For example:
Yellow → central idea
Green → argument
Blue → concept or definition
Pink → passage to revisit
The Highlights panel displays small color controls for changing the color assigned to an existing highlight.
Highlight color is internal SEP Reader metadata and is deliberately omitted from exported Markdown.
New highlights also store contextual information about the section of the article in which they were created.
SEP Reader identifies a nearby article heading and associates it with the highlight.
For example:
3.2 Significant Aspects of the Published Aufbau
This section name is displayed above the quotation in the Highlights panel.
Highlights created before this feature was introduced may appear as:
No section
The right-hand panel can switch between:
- Notes
- Highlights
The Highlights view presents each saved passage as an independent block separated from the next.
Each item can contain:
- the article section;
- navigation and note actions;
- highlight color controls;
- the complete highlighted passage.
Each item in the Highlights panel includes an action for returning to the highlighted passage in the article.
When activated:
- the article scrolls to the corresponding highlight;
- the passage is positioned approximately in the center of the reading area;
- a temporary visual indication helps identify it.
This makes the Highlights panel useful as a secondary navigation structure for the article.
A highlight can be inserted directly into the article's note.
SEP Reader inserts it using standard Markdown blockquote syntax:
> Highlighted passageThe reader can then write commentary, analysis, references, or questions around the quotation.
SEP Reader can export the work associated with an article to a .md
file.
The exported document includes:
- the SEP entry title;
- the original SEP URL;
- the user's notes;
- saved highlights;
- the section associated with each highlight.
Highlight colors are not exported.
The output intentionally uses conservative Markdown syntax to maximize compatibility with other Markdown editors, static-site tools, note-taking applications, and document processors.
An exported document may look like:
# Rudolf Carnap
Source: https://plato.stanford.edu/entries/carnap/
# Notes
## Aufbau and epistemology
Personal notes about the article.
# Highlights
## 3.2 Significant Aspects of the Published Aufbau
> In the published Aufbau this abstemious bracketing policy is applied very strictly.SEP Reader reserves level-one Markdown headings for the main structure of exported documents:
# Entry title
# Notes
# HighlightsHeadings written inside the note are therefore shifted down one level during export.
In SEP Reader Exported
# ##
## ###
### ####
#### #####
##### ######
This allows notes to be written naturally inside the application without requiring the user to manually account for the hierarchy of the final exported document.
The following shortcuts are currently implemented:
Shortcut Action
Ctrl+F Find text inside the current
article
Ctrl+D Add or remove the current article
from Favorites
Ctrl+Shift+R Toggle between web view and Reading
Mode
Ctrl+Shift+N Show or hide the Notes panel
Ctrl+Shift+H Enable or disable automatic
highlighting
Article-specific shortcuts only act when the current page is a supported SEP entry.
SEP Reader is being developed around a local-first model.
Application data is currently stored under:
~/.local/share/sep-reader/
This includes files such as:
favorites.json
recents.json
reader-preferences.json
notes-preferences.json
notes/
Notes are stored as Markdown files.
Some web-content state, including reading position and highlights, is currently persisted using WebKit local storage associated with SEP pages.
The storage architecture may change during the beta as the project moves toward a more explicit and portable data model.
SEP Reader is intended to keep the reader's academic work under the reader's control.
Core principles include:
- local storage by default;
- plain-text notes;
- portable exports;
- no required SEP Reader account;
- no mandatory proprietary cloud service.
An Internet connection is currently required to retrieve SEP articles because offline article storage has not yet been implemented.
SEP Reader is currently developed with:
- Python 3;
- GTK 4;
- libadwaita;
- WebKitGTK 6;
- PyGObject.
On Ubuntu/Linux Mint-based systems, the current development dependencies can be installed with:
sudo apt update
sudo apt install \
python3 \
python3-gi \
gir1.2-gtk-4.0 \
gir1.2-adw-1 \
gir1.2-webkit-6.0Clone the repository and enter the project directory:
git clone https://github.com/YOUR-USERNAME/sep-reader.git
cd sep-readerMake the launcher executable if necessary:
chmod +x sep_reader.pyRun:
./sep_reader.pyor:
python3 sep_reader.pyThe repository URL above should be replaced with the final public repository URL.
SEP Reader is gradually being split into focused modules instead of concentrating all behavior in the main application file.
sep-reader/
├── sep_reader.py
├── sep_reader/
│ ├── __init__.py
│ ├── constants.py
│ ├── storage.py
│ ├── reader.py
│ ├── reading_position.py
│ ├── toc.py
│ ├── notes.py
│ ├── highlights.py
│ └── article_find.py
└── README.md
Broadly:
sep_reader.py--- main window, interface, event handling, and feature coordination.constants.py--- application constants and local paths.storage.py--- JSON persistence helpers.reader.py--- Reading Mode transformation and reader controls.reading_position.py--- reading-position persistence and restoration.toc.py--- article table-of-contents behavior.notes.py--- note persistence, Markdown rendering, and Markdown export.highlights.py--- highlight creation, persistence, restoration, colors, and navigation.article_find.py--- in-article search and match navigation.
SEP Reader has, so far, been implemented entirely through AI-assisted coding.
The project began without the human collaborator having prior programming experience. Rather than first building the application from a conventional hand-written codebase, development has taken place as an iterative conversation between the project's human author and an AI coding assistant.
The human collaborator has been responsible for:
- defining the purpose and scope of the application;
- deciding which problems the application should solve;
- specifying desired behavior and interaction patterns;
- choosing the visual direction;
- testing every development step on a real Linux system;
- reporting errors, warnings, regressions, and usability problems;
- evaluating whether implemented behavior actually feels useful;
- deciding which features should be kept, changed, simplified, or removed;
- directing the project's roadmap.
The AI assistant has been used to:
- explain unfamiliar programming and Linux concepts;
- propose implementation strategies;
- write and modify Python, GTK, WebKit, JavaScript, CSS, and Markdown-related code;
- split functionality into modules as the application grew;
- interpret terminal errors and runtime warnings;
- revise implementations after real-world testing;
- prepare complete replacement files for development iterations;
- help document the resulting architecture and behavior.
The development loop has generally followed this pattern:
Idea or usability problem
↓
Human describes desired behavior
↓
AI proposes and implements a small change
↓
Human runs the code locally
↓
Human reports the actual result
↓
AI diagnoses or refines the implementation
↓
Human evaluates the new behavior
↓
Next iteration
This means the AI has generated the implementation code, but the application has not been produced autonomously.
Its behavior and direction have emerged from repeated human decisions, testing, criticism, and refinement. Many features required several iterations because the first implementation exposed issues that only became apparent when the application was used interactively.
Examples include:
- redesigning the notes interface after evaluating how it felt in actual use;
- changing highlight interactions to preserve normal text selection;
- using WebKit's native context menu instead of replacing it with a custom one;
- fixing table-of-contents scrolling behavior after testing;
- reorganizing highlight actions when the first layout felt too crowded;
- separating highlight color metadata from exported Markdown for better interoperability;
- normalizing Markdown heading levels during export;
- replacing deprecated GTK file APIs after runtime warnings appeared;
- correcting WebKitGTK callback signatures based on behavior in the target environment.
The project therefore also serves as an experiment in iterative AI-assisted software development by a non-programmer, where the human participant acts as product designer, tester, decision-maker, and domain expert while AI performs much of the implementation work.No claim is made that AI-generated code is inherently correct or production-ready. The beta should be treated accordingly: code needs continued review, testing, refactoring, accessibility work, and security consideration as the project matures.
SEP Reader is still under active development.
Current limitations include:
- an Internet connection is required to load articles. Because there is no offline article library yet;
- Markdown support in the editor and preview is partial;
- there is no cross-device synchronization;
- highlights and some web state currently depend on WebKit local storage;
- the persistent data model has not yet been declared stable;
- beta releases may introduce incompatible changes.
Important notes should be backed up while the application remains in beta.
The following areas represent intended or plausible directions for continued development. They are not guarantees of implementation or necessarily listed in development order.
The home screen could evolve into a research library containing:
- saved articles;
- collections;
- tags;
- reading status;
- last-read dates;
- filters;
- library-wide search.
A future offline system could support:
- downloading SEP entries;
- reading without an Internet connection;
- detecting updated SEP articles;
- updating stored copies;
- keeping annotations associated with local copies.
Any implementation involving local copies or redistribution of SEP content will need to respect the applicable terms governing SEP content.
The current highlight model already stores text, section, and color.
Possible extensions include:
- highlight tags;
- comments attached directly to highlights;
- filtering by color;
- filtering by article section;
- searching across highlights;
- thematic grouping;
- selective export;
- immediate panel synchronization when highlights are created or removed.
Future editor and preview support may include:
- links;
- numbered lists;
- task lists;
- fenced code blocks;
- nested blockquotes;
- tables;
- horizontal rules;
- more robust heading behavior;
- closer CommonMark or GitHub Flavored Markdown compatibility.
Plain-text portability should remain a priority.
Markdown export is the first interoperability layer.
Possible future formats include:
- HTML;
- PDF;
- plain text;
- Markdown with YAML metadata;
- Pandoc-oriented export;
- bibliography-aware export.
Users may eventually be able to choose which annotations are included in an export.
A major long-term direction is to connect philosophical reading with reference management.
Potential areas include:
- bibliographic metadata;
- references cited by SEP entries;
- DOI support;
- BibTeX import/export;
- Zotero interoperability;
- relationships between SEP articles, notes, and external academic literature.
A future visual workspace could represent relationships among:
- philosophers;
- concepts;
- arguments;
- works;
- articles;
- notes;
- quotations.
This could develop into a canvas-based concept-mapping system inspired by digital whiteboards and diagramming tools.
A future personal library could search simultaneously across:
- article titles;
- notes;
- highlights;
- tags;
- downloaded article text;
- bibliographic metadata.
Local-first does not necessarily mean local-only.
Possible future synchronization work includes:
- WebDAV;
- Markdown-note synchronization;
- preference synchronization;
- highlight synchronization;
- conflict resolution;
- multi-device workflows.
Synchronization should remain optional and should preserve user-accessible data formats.
A future side panel may provide optional AI-assisted research tools.
Possible uses include:
- asking questions about an article;
- explaining difficult passages;
- comparing philosophical concepts;
- generating study questions;
- exploring relationships among notes;
- helping locate relevant bibliography.
Any AI integration should make clear:
- which provider is being used;
- what information is sent externally;
- what article or note context is included;
- whether the feature can be disabled;
- how user data is handled.
AI should complement engagement with primary and scholarly material rather than replace it.
Accessibility work should include systematic testing of:
- full keyboard navigation;
- accessible labels;
- screen readers;
- contrast;
- text scaling;
- focus states;
- narrow-window behavior.
GTK and libadwaita provide useful foundations, but accessibility still requires explicit testing and design work.
The interface will continue to be refined for:
- smaller windows;
- large displays;
- open notes panels;
- visible or hidden navigation sidebars;
- different display scaling factors.
The visual goal is a restrained, readable desktop application consistent with the GNOME/libadwaita ecosystem.
Planned distribution work includes:
- stabilizing the beta;
- adding application metadata and final iconography;
- producing installable beta builds;
- preparing Flatpak packaging;
- evaluating eventual Flathub distribution.
As SEP Reader grows, development aims to preserve several principles.
Interoperability. SEP Reader should work alongside existing academic tools rather than trying to lock the entire research workflow into one application.
Modularity. New capabilities should be structured so that the project can grow without becoming a single unmaintainable codebase.
Human control over AI. AI may assist implementation and, potentially, research workflows, but human decisions, verification remain central.
The current version should be treated as a development beta.
Core reading and annotation workflows are functional, but interface decisions, persistence, export behavior, and architecture are still being tested and refined.
Bug reports, usability observations, and contributions are particularly valuable during this stage.
A project license should be selected before the first public release.
Until a LICENSE file is added, no open-source license should be
assumed merely because the source code is publicly visible.
SEP Reader is an independent project built as a reading and annotation interface for the Stanford Encyclopedia of Philosophy.
It is not an official product of Stanford University or the Stanford Encyclopedia of Philosophy.
Before implementing or distributing features involving offline copies, bulk retrieval, or redistribution of SEP material, the project should review and comply with the terms applicable to SEP content.