About Cosma


Cosma was created during the HyperOtlet research programme. It was imagined by Arthur Perret, as part of his PhD research under the supervision of Bertrand Müller and Olivier Le Deuff. In 2018 and 2019, Olivier led a mapping project named Otletosphere, with version 2 developed by Guillaume Brioudes. In 2020, Arthur challenged Guillaume to build a prototype based on the Otletosphere’s source code to visualize his research documentation as an interactive network. This is the starting point of what became Cosma.

Today, Cosma is made primarily by Arthur Perret and Guillaume Brioudes. Arthur is in charge of the design and documentation of Cosma. Guillaume authors most of the source code and maintains the software.

Why did we create Cosma?

There are many non-linear writing tools, including a recent wave of “tools for thought” that use visualization, such as Roam and Obsidian. However, we belong to a niche of users for whom these tools weren’t entirely satisfactory: people who write scientific texts and need to create lasting research documentation; knowledge workers with a preference for plain text, familiar with Markdown and Pandoc-based tools such as Zettlr and Stylo.

We wanted a tool that would work alongside any text editor, using open formats, and that would be built with Web publishing in mind. A tool that would not automate everything but rather use metadata and unique identifiers to make data more portable. A tool that would encourage knowledge organization for ideation, using the graph structure for synthesis and not just analysis. This tool did not exist, so we ended up creating it.

An important thing to keep in mind about Cosma is that this is a research experiment: it was created to help investigate the use of hypertext for knowledge organization, and it supports primarily scientific writing. This has consequences for Cosma’s design, which may not fit all manners of non-linear writing.

What is Cosma?

Most of Cosma is made of pre-existing ideas and techniques (hypertext, graph visualization, backlinks…), with two uncommon choices that define the program’s identity:

Not a text editor

Firstly, Cosma is not a note-taking application. There is no text editor. So a direct comparison with fully fledged writing software like Obsidian has limited relevance.

Cosma only reads files, and generates a visualization of these files and their connections. It is not meant to replace your favorite writing tool but to work alongside it.

Why not make a text editor? Three reasons:

  • It was first and foremost a pragmatic decision: we did not have the means to develop a text editor, which is an extremely complex task. Also, convincing people to switch from their favorite writing tool is an uphill battle we did not care to fight.

  • The decision was also a matter of preference: we like programs that pair with a writing tool of our choice, allowing us to switch between different text editors depending on the situation. The presentation app Deckset is a good example of this: write in any text editor, design and present the slides with the app.

  • And it was also a strategic choice: in the space of non-linear documentation, there are very few visualization-only tools. This means less competition with other programs for the users’ attention.

An app within an app

The other uncommon choice we made is about the architecture of Cosma.

As a user, you install a program called cosma, which has a command-line interface. You then use this program to generate an HTML file, the cosmoscope, which behaves like a self-contained application, with text, menus and buttons. The cosmoscope is where Cosma’s usefulness resides. It is the app within the app.

% cosma modelize --project my-notes  
[Cosma v.2.0.0] My Notes my-notes.yml
Building cosmoscope… (source type: csv)
Cosmoscope generated (128 records)

For most visualization software, functionality exists within an installable program, and exports are either static or with very limited interactivity. For Cosma, we wanted to have just as much functionality in the exports as within the app. We were influenced by digital notebooks, publishing software and web applications in general, where users have access to data but also functionality. So we designed Cosma around an app-like export, generated by a very light cosma command-line program.

The cosmoscope can be used on its own. It doesn’t require the cosma program, just a web browser. It doesn’t require an Internet connection. It can be shared just as any other file attachment in email, chat, file transfer programs, etc. Thus, whether you are the person who creates it or the one who consults it, you have the same heuristic capacities.

Who is this for?

Cosma is an interface for wiki-like data, presenting it in a way which helps to analyze, synthesize and share information. Any kind of knowledge work which involves describing things and the relationships between them can make use of Cosma. So this is a program with many applications for teachers, students, researchers, librarians, designers, journalists, engineers…

Check the Examples page to discover a few use cases.

Cosma is available free of charge, and its code is freely reusable under the conditions permitted by the GNU GPL 3.0 license. Our goal is as Andy Matuschak put it: to create tools that help create generalizable observations within the framework of scientific reflection. We do not offer dedicated support but welcome bug reports to help us maintain the program.

Cite Cosma in your work:

Arthur Perret, Guillaume Brioudes, Clément Borel, & Olivier Le Deuff. (2023). Cosma (2.2.1). https://doi.org/10.5281/zenodo.5412314 https://hal.science/hal-04271539