Light Academia

Local-first research notes with an agent-assisted project workspace.

A research note shown in the split editor and preview workspace.

Vibe coding disclaimer

This project was developed with substantial AI assistance and prioritizes functionality over software engineering rigor. The code may contain errors, insecure assumptions, or unexpected behavior. Review and test it carefully before using it with important data or in a production environment.

Security and safety disclaimer

This tool is expected to be run locally in environments with no access to highly sensitive data. While it uses Web technologies for maximum portability, it should never be exposed over the Internet.

It is the user's responsibility to ensure that their agent set-up is adequately sandboxed. The developers of the tool are not responsible for any unwanted or undesirable behaviour of the tool or of the AI agent.

Run

python -m pip install -r requirements.txt
python -m streamlit run app.py

Use a custom notebook folder:

python -m streamlit run app.py -- --notebook ./my-notebook

On first launch, Light Academia copies the stock projects from starter-notebook/ into the configured notebook folder and creates a .ready marker there. Existing projects are preserved. Later launches skip this setup while the marker exists.

Use a custom automatic commit inactivity period:

python -m streamlit run app.py -- --autocommit-seconds 600

Use a custom researcher tools folder:

python -m streamlit run app.py -- --tools ./my-tools

The tools folder can contain SKILL.md describing available researcher-specific commands, such as cluster, cloud, or wandb helpers.

Each project can also contain its own SKILL.md for project-specific guidance on how to use those tools.

Note actions

The active note can define reusable agent actions. Actions are parsed locally with markdown-it-py and appear in the selector beside the agent prompt.

```action
name: Compare validation accuracy

Retrieve the relevant results.
Plot the comparison.
Add the results to this note.
```

The action body can be run by itself or combined with an additional prompt. In the preview, a bolt button above each action block selects that action in the pinned agent controls without running it immediately.

Boards

Boards are note-local, agent-refreshed dataframes. A board defines how to fetch its rows and may expose actions for each row:

```board
name: Experiments
actions:
- Resume: Resume the selected experiment
- Troubleshoot: Tail the log file and summarize the findings
filters:
- Name
- Cluster: dropdown
- Status: dropdown
columns:
- Name
- Cluster
- Status
- Epoch

Fetch experiments from the cluster that have run within the last week.
```

Refreshing this example immediately runs the Robot to write data/board-experiments.csv. When the file exists, the preview displays it as an interactive dataframe. Refreshing never executes the board's row actions. Each declared action becomes a button column. Refreshes and row actions run with the normal stoppable progress display.

Board filters are local and do not call the Robot. A bare column name creates a case-insensitive text filter. Add : dropdown to select from the distinct values in that CSV column. The currently supported types are text and dropdown.

The optional columns list defines the required CSV schema and display order. Light Academia includes it in the Robot's refresh instructions and warns when the generated CSV is missing a requested column.

Project images

Generated images belong in the selected project's assets/ directory and can be embedded in notes with project-relative Markdown:

![Validation accuracy](assets/validation-accuracy.png)

The preview resolves supported local image links only within that project's assets/ directory.

Agent

The app uses an agent abstraction in lightacademia/agents.py.

The agent instructions are stored in AGENT_PROMPT.md. Review this file before using the app and adjust its rules for your environment and risk tolerance. Keep the {{project_name}}, {{project_dir}}, {{tools_dir}}, {{tools_root}}, {{current_note}}, and {{user_prompt}} placeholders where their runtime values should be inserted.

Select the agent implementation at startup:

python -m streamlit run app.py -- --agent codex
python -m streamlit run app.py -- --agent claude

The default implementation uses the Codex CLI:

• Runs codex exec
• Uses codex exec --json to stream detailed progress into the pinned agent section
• Displays Codex events directly without a separate summarization model call
• Uses the selected project as the working root
• Adds a temporary copy of the configured tools folder as an auxiliary workspace
• Uses workspace-write sandboxing
• Enables outbound network access for commands inside the Codex workspace-write sandbox
• Tells Codex to write derived outputs under data/ and scratch scripts under code/
• Tells Codex to read project-level SKILL.md when present
• Tells Codex to read and run tools from the configured tools folder
• Prevents Codex from editing the configured tools folder by exposing only a temporary copy
• Tells Codex not to access folders outside the selected project and tools folder
• Tells Codex not to download or install software from the Internet
• Tells Codex to interact with compute clusters only through configured tools
• Tells Codex not to run git commands
• Leaves git checkpoints and commits to the application
• Uses [agent]-prefixed commit messages for commits created after agent actions

Claude Code CLI support is also available with --agent claude:

• Runs claude --print --output-format stream-json --verbose
• Uses the selected project as the working root
• Adds a temporary copy of the configured tools folder with --add-dir
• Uses acceptEdits permission mode and allows common file/shell tools
• Streams Claude JSON events into the same pinned agent progress section