https://github.com/ariana-dot-dev/ariana
Observability and runtime visualization for JS/TS/Python code with zero code change
https://github.com/ariana-dot-dev/ariana
ai cursor debugging extension python vscode
Last synced: 9 months ago
JSON representation
Observability and runtime visualization for JS/TS/Python code with zero code change
- Host: GitHub
- URL: https://github.com/ariana-dot-dev/ariana
- Owner: ariana-dot-dev
- License: agpl-3.0
- Created: 2025-02-21T21:55:22.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-16T09:56:53.000Z (about 1 year ago)
- Last Synced: 2025-09-25T22:42:34.911Z (9 months ago)
- Topics: ai, cursor, debugging, extension, python, vscode
- Language: TypeScript
- Homepage: https://ariana.dev
- Size: 358 MB
- Stars: 131
- Watchers: 0
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-agent-orchestrators - ariana - The IDE of the future. (Parallel Agent Runners)
README
Ariana: Debug what happens when your code runs, using Coding Agents & with zero code change
Ariana is a CLI to automatically add observability to your code and an IDE extension to consume it & provide context-aware debugging capabilities to coding agents. You don't have to change any code in your codebase or specify breakpoints. Currently supports JS/TS & Python.
## ✨ Key Features
Use Ariana VSCode extension to :
- 🕵️ Hover over any expression to see its **last recorded values**
- ⏱️ See **how long** it took for any expression in your code to run.
- 🧵 *Provide runtime history to* **coding agent** *for context-aware debugging* (WIP)
## 💾 How to install
| IDE | Command |
|-----|---------|
| **VSCode** | [Click here to install](vscode:extension/dedale-dev.ariana) or [get it from the marketplace](https://marketplace.visualstudio.com/items?itemName=dedale-dev.ariana) |
| **Cursor / Windsurf (VSCode Forks)** | [Download from open-vsix](https://open-vsx.org/extension/ariana/ariana) then drag the `.vsix` file into your extensions panel in Cursor/Windsurf... |
## 🧵 How to use
Follow the **Getting started** instructions in the Ariana extension panel for the most up-to-date guidance. Below is a summary:
#### 1. Install the `ariana` CLI
The Ariana VS Code extension will guide you through installing the `ariana` CLI if it's not already present on your system. It will detect available package managers (like npm or pip) and provide commands to run directly from the extension.
If you prefer to install it manually, here are the common commands:
| Package Manager | Command |
|-----------------|--------------------------------|
| **npm** | `npm install -g ariana` |
| **pip** | `pip install ariana` |
| | `python -m pip install ariana` |
| | `python3 -m pip install ariana`|
#### 2. Observe your code with `ariana`
To collect runtime information, run your usual build/execution command, but prefix it with `ariana`. This tells the CLI to instrument a copy of your code (in a local `.ariana` directory) and observe its execution.
```bash
ariana
```
For example:
| Codebase Type | Command |
|-----------------|----------------------------------------------|
| **JS/TS** | `ariana npm run dev` |
| **Python** | `ariana python myscript.py --some-options` |
Run this in each terminal where you execute a part of your application you want to observe.
#### 3. View Traces in VS Code
Open the Ariana panel by clicking on its icon in the Activity Bar.
- If you've run `ariana` on multiple projects, you might be prompted to select the run you want to focus on.
- Traces from your code's execution will appear in the **Traces** tab.
#### 4. Analyze Traces & Hover Over Code
Once traces are loaded, Ariana provides insights directly in your editor:
- 🗺️ **Execution Highlighting**: See which parts of your code ran.
| Highlight Color | Meaning |
|-----------------|-------------------------------------------------|
| 🟢 **Green** | Code segment ran successfully. |
| 🔴 **Red** | Code crashed here. |
| ⚫ **Grey/None** | Code segment didn’t run or couldn't be recorded. |
- 🕵️ **Value Hovers**: Hover over any expression in your code to see its last recorded values and execution time.
#### 5. (Optional) Use AI to Understand Traces (WIP)
In the Ariana panel, you can copy the collected traces. You can then paste these into an AI coding assistant with a prompt like:
```
Using the debugging traces above and your knowledge of the codebase please do
```
Tip: Use an agent with a large context window, as traces can be verbose.
*Coming soon: More compact traces and an integrated AI agent for runtime analysis and fixes.*
----------------------------------------
## Preview :
*To test Ariana before using it on your own code:*
```
git clone https://github.com/dedale-dev/node-hello.git
cd node-hello
npm i
ariana npm run start
```
-----------------------------------------
## Troubleshooting / Help
😵💫 Ran into an issue? Need help? Shoot us [an issue on GitHub](https://github.com/dedale-dev/ariana/issues) or join [our Discord community](https://discord.gg/Y3TFTmE89g) to get help!
## Requirements
### For JavaScript/TypeScript
- A JS/TS node.js/browser codebase with a `package.json`
- The `ariana` command installed with `npm install -g ariana` (or any other installation method)
### For Python
- Some Python `>= 3.9` code files (Notebooks not supported yet)
- The `ariana` command installed with `pip install ariana` **outside of a virtual environment** (or any other installation method)
## Supported languages/tech
| Language | Platform/Framework | Status |
|----------|-------------------|---------|
| JavaScript/TypeScript | Node.js | ✅ Supported |
| | Bun | ✅ Supported |
| | Deno | ⚗️ Might work |
| **Browser Frameworks** | | |
| JavaScript/TypeScript | React & `.jsx` / `.tsx` | ✅ Supported |
| | JQuery/Vanilla JS | ✅ Supported |
| | Vue/Svelte/Angular | ❌ Only `.js` / `.ts` |
| **Other Languages** | | |
| Python | Scripts / Codebases | ✅ Supported |
| | Jupyter Notebooks | ❌ Not supported (yet) |
## Code processing disclaimer
We process and temporarily store for 48 hours your code files on our server based in EU in order to instrument them and help you debug afterwards. It is not sent to any third-party including any LLM provider. An enterprise plan will come later with enterprise-grade security and compliance. If that is important to you, [please let us know](https://discord.gg/Y3TFTmE89g).
## Licence
Code generated and/or transformed by Ariana is yours and not concerned by the following licence and terms.
Ariana is released under AGPLv3. See [LICENCE.txt](LICENCE.txt) for more details.