Skip to content
OstenHunPublic

About

Local research evidence CLI: connect paper claims to project decisions and export context for AI agents.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

61 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Danseo

Danseo — research evidence, project decisions.

Bring research evidence into project decisions.

License: MIT Node.js 22 or 24 LTS Development preview

English · 한국어 · Install the skill · Quick start · Project structure · Documentation · Contributing

Summary: A development preview that connects paper discovery, source collection, analysis, and comparison in local files, using your existing AI agent, a CLI, and evidence-linked research views.

Overview

A paper summary alone rarely gives you enough context to use a method in a project. You also need the evaluation conditions, exact source locations, and a record of why you chose to apply, test, or defer it.

Danseo (단서, “clue” in Korean) keeps that context available for your next conversation. Paper records hold reusable research evidence; Application records hold project-specific decisions. Multiple projects can reference the same paper without sharing the same adoption decision.

  • Keep discovery resumable. Save search rounds, stable paper numbers, and the source and edition shown when you selected a paper.
  • Read against the source. Connect PDFs, paper claims, answers, and notes while preserving conditions, limitations, and unread areas.
  • Explore the evidence. Select papers or comparison criteria to inspect source locations and distinguish source relationships from AI proposals.
  • Use your existing agent. The agent searches, downloads authorized sources, reads papers, and prepares comparisons. Danseo connects and checks the resulting files; it does not call a model.

After installing the skill, try “I want to read Attention Is All You Need.” The paper-reading orientation asks your agent to discover a bounded neighborhood of prior and follow-up research and create an interactive HTML in your request language. Select a paper to inspect its connections, or expand a separate concept background and return to the focal paper. Search availability and source access determine coverage; the map is not an exhaustive literature review.

Stage What Danseo records
Discover and select Search rounds, stable numbers, sources, editions, and reasons for selection
Collect sources Managed PDF copies or existing-file links, identity checks, and explicit consent for draft editions
Analyze and resume Shared Paper cards, topic-specific Markdown answers and notes, follow-up questions, and reading positions
Compare research Currently supported claims, evaluation conditions, limitations, source locations, and reasons for AI proposals

The CLI workflow and standalone skill views are separate entry points: use the skill for a paper-relationship HTML, or build the full CLI to manage a topic from discovery through a read-only comparison view.

Install the skill

For standalone paper-relationship HTML, you need Node.js 22 or 24 and the complete skills/danseo folder. No npm package installation, build, or server is required. Use an installed, signed-in agent such as Codex, Claude Code, or Antigravity CLI with access to your paper files and permission to run Node commands. A folder path pasted into an ordinary web chat is not sufficient.

1. Download the source

git clone https://github.com/OstenHun/danseo.git
cd danseo
node --version

Without Git, use Code → Download ZIP, extract it, and open a terminal in the folder containing README.md and skills/. Install the entire danseo skill folder: copying only SKILL.md omits the generators, references, and design assets.

2. Install for your agent

These are personal installation locations used across projects. ~ means your home directory. The Argon instructions refer to using an Argon model through Antigravity CLI (agy).

Agent Installation folder Invoke in a new chat
Codex ~/.agents/skills/danseo $danseo or the skill picker
Claude Code ~/.claude/skills/danseo /danseo
Argon · Antigravity CLI ~/.gemini/config/skills/danseo /danseo

Host instructions: Codex · Claude Code · Antigravity. Use agy models to check available Argon model names before selecting one.

Expand the example for your operating system and choose one destination. The examples preserve existing installations. If you already use ~/.codex/skills/danseo or a project-specific installation, check the path your agent actually loads before adding another copy.

Windows · PowerShell

Run from the repository root. The default is Codex; replace the destination line for Claude Code or Argon.

$danseoTarget = Join-Path $HOME '.agents/skills/danseo'
# Claude Code: Join-Path $HOME '.claude/skills/danseo'
# Argon (agy): Join-Path $HOME '.gemini/config/skills/danseo'

if (Test-Path -LiteralPath $danseoTarget) { throw "Check the existing installation: $danseoTarget" }
New-Item -ItemType Directory -Force -Path (Split-Path $danseoTarget -Parent) | Out-Null
Copy-Item -LiteralPath './skills/danseo' -Destination $danseoTarget -Recurse -ErrorAction Stop
node --test "$danseoTarget/scripts/research-evidence.test.mjs"
macOS / Linux · Bash or Zsh

Run from the repository root. The default is Codex; replace the destination line for Claude Code or Argon.

danseo_target="$HOME/.agents/skills/danseo"
# Claude Code: danseo_target="$HOME/.claude/skills/danseo"
# Argon (agy): danseo_target="$HOME/.gemini/config/skills/danseo"

if [ -e "$danseo_target" ] || [ -L "$danseo_target" ]; then
  printf 'Check the existing installation: %s\n' "$danseo_target"
else
  mkdir -p "$(dirname "$danseo_target")" &&
    cp -R ./skills/danseo "$danseo_target" &&
    node --test "$danseo_target/scripts/research-evidence.test.mjs"
fi

A test result of fail 0 confirms the bundled validator regression checks. It does not confirm that your model discovered the skill or read a paper correctly.

3. Check in a new chat

Start a new chat, select Danseo using the invocation above, and try the graph prompt below. If it is missing, restart the app or CLI and check that SKILL.md, scripts/, references/, and assets/ are in the same installed folder. You can also ask the agent to read the installed SKILL.md by its absolute path. If it loads a different copy, specify the intended path.

GitHub changes do not automatically update your installed copy. To update, download the latest source, back up the existing skill outside the host's skill search paths, then copy and check the complete folder again.

Companion skills and output language

Instructions, agent metadata and default synthetic examples are in English. Explanations and generated content follow your requested language; English instructions do not force English answers.

Complete source folder Use it for
skills/danseo Paper discovery, records, evidence and research relationship views
skills/danseo-reading Questions, source feedback and concept learning views
skills/paper-to-project Comparing paper/project conditions and choosing an application action

Install a companion using the same procedure, replacing both the source and destination folder name with danseo-reading or paper-to-project. Invoke it by that name, or explicitly read its installed SKILL.md. Each folder contains its own required resources. The application skill is guidance only and needs no Node runtime; for the learning generator run node --test <installed-danseo-reading>/scripts/learning-view.test.mjs.

For standalone research and learning HTML, set candidate language to en or ko to match the request. The renderers preserve supplied prose and quotations. Older candidates without this field retain their original defaults: English research UI and Korean learning UI. Other requested prose languages use English fixed controls; no live language switch or automatic translation service is included. Existing saved HTML must be regenerated to receive changes. CLI/native comparison controls remain English.

Generate a paper-relationship graph

Use the same request with any of the three agents. Replace the example paths with actual absolute paths on your computer. Select $danseo in Codex or /danseo in Claude Code or Antigravity first, or prefix your request with that invocation.

Use the Danseo skill to create a standalone HTML relationship graph for these papers.
Paper folder: C:/research/my-topic/papers
Research question: How does each paper connect retrieved evidence to answers and evaluate it?
Output folder: C:/research/my-topic/output
Write the explanations in English.

On macOS or Linux, use a real path such as /Users/me/research/my-topic/papers or /home/me/research/my-topic/papers. Your agent must be able to read the PDFs. Finding additional papers also requires search and download tools.

The default workflow is check sources and editions → write relationships and evidence → separate source records from AI proposals → check the overview and quantities → generate shared HTML → inspect the rendered view. Source relationships retain page or section locations; suggested connections remain proposals. Keep the candidate JSON and evidence files alongside the HTML so later revisions can reuse the same generator. See source verification, overview and quantity checks, and performance verification.

Views use short paper names, topic grouping, and connections around the selected paper by default. You can filter evidence status and relationship types, or show all connections. Full titles and relationship data remain in the details; topic grouping is identified as AI editorial interpretation. Danseo targets local PC and laptop use. Verify the desktop view before delivery.

Select a paper or edge to inspect evidence, conditions, and source/AI labels. Correct the source or input after a failed check. If browser tools are unavailable, the agent must report that visual inspection was not performed. Passing automated checks does not certify every relationship interpretation.

To review an existing graph:

Recheck the existing candidate JSON and evidence files against the original PDFs.
Output folder: C:/research/my-topic/output
Correct any mixing of source relationships and AI proposals, or mismatched record,
document, or pair counts. Preserve the previous output and create a new HTML file.
Report what you actually inspected in the rendered view.

Quick start

Build the full CLI

Use the full CLI to manage topic history, Paper cards, project decisions, analysis, and comparisons. The standalone graph skill above does not require this build.

Requires Node.js 22 or 24 LTS and npm; Node 24 is recommended for development. Run from the downloaded source folder:

npm ci
npm run build
node ./dist/cli.js validate --workspace ./examples/minimal --json

The synthetic example reports ok: true, 3 records, 2 projects, and an expected draft warning. Validation checks structure and references. See runtime support and the English CLI guide.

Start with your own topic

Give your agent the absolute Danseo folder and a private topic directory. Discovery also requires the agent's search tools.

Read skills/danseo/SKILL.md in this Danseo folder.
Find papers for my research question in my private topic directory.
Show the sources, editions, and reasons so I can choose.
  1. Select candidates, then ask the agent to collect their original sources.
  2. Ask a question about a selected paper; retain the answer and exact source locations.
  3. Ask the agent to compare papers using the checked evidence.

In a new chat, provide the same tool, skill, and topic directory. The English end-to-end guide covers discovery → collection → analysis → comparison. See the detailed English analysis and comparison references.

Connect existing cards and projects

Paper records hold claims and sources; Application records hold project-specific decisions. Register explicit cards and projects using the synthetic workspace, then give your agent the four connection values.

validate checks structure and references; list and show read cards. export includes the selected question and full linked cards as Markdown or JSON, preserving content, comments, extension fields, and source locations. --out creates new files only.

node ./dist/cli.js export --workspace ./examples/minimal --project demo --application app-demo --include-drafts --format markdown

The fixture is a draft, so it requires --include-drafts. This option does not change review status. See the card model.

Project structure

Danseo is one TypeScript/Node.js package plus a portable agent skill. The CLI and read-only comparison app share the file-based core; the skill includes its own standalone HTML generators and assets.

src/
  cli.ts                 Commands, options, output, and exit codes
  core/                  Cards, topics, source collection, analysis, reviews, and comparison
  web/                   Read-only comparison server and browser UI
  views/                 Shared map presentation and reading styles
schemas/                 Card, workspace, and relationship schemas
skills/danseo/           Agent instructions, references, standalone generators, and assets
examples/minimal/        Synthetic workspace for validation and export
scripts/                 TypeScript build and documentation tools
tests/                   TypeScript regression tests, helpers, and package checks
docs/                    Usage guides, data formats and evidence-check contracts

A topic folder keeps selections, collected-source records, and topic-specific analysis. A separate workspace.json registers reusable cards, projects, claim-review inputs/results, and optional relationships. The same Paper can support separate answers in different topics. Author claims, AI interpretations, project observations, and adoption decisions remain distinct.

Private papers and records belong outside shared product source. work/, workspaces/, and private/ are local-only areas excluded from distribution. Exports include full card text and absolute local paths; inspect them before sharing.

Status and limitations

Version 0.1.0-dev.1 is a development preview. The CLI and file formats may change.

  • Included: discovery records, source collection, topic-specific analysis and resumption, evidence-linked comparison, existing-card export, and standalone relationship HTML.
  • Not included: a card editor, automatic experiments or submissions, or an MCP server. The research comparison app targets desktop browsers; the optional learning skill is installed separately from the same source.
  • Language: standalone research HTML supports Korean or English controls and guidance through candidate language: "ko" or "en"; the agent sets it to match your request. Old inputs default to English. Agent-authored prose follows your requested language. Original titles, quotations, identifiers and saved records are preserved. CLI/native comparison controls, diagnostics, skill instructions and usage references remain English. There is no live language switch. Output-language rules. Korean README editions and synthetic content remain available; internal work records stay local.

Danseo itself needs no model key, database, or permanent server and makes no outbound requests. topic compare runs a read-only loopback server only while you use the view; stop it with Ctrl+C. Your agent's search, downloads, and model transmissions follow that agent's settings and permissions.

Structural checks and source-support reviews do not establish experiment reproduction or reader understanding. See runtime support, the roadmap and distribution boundaries.

Documentation

Goal Start here Language
Install and request a standalone graph Skill installation · Graph prompt English
Manage a topic from discovery to comparison CLI and agent guide English
Understand the bundled skill Skill overview English
Inspect analysis, reviews, and comparison formats Documentation index English
Use logos and banners Brand assets English

Contributing and license

Bug reproductions, clearer documentation, synthetic examples, and reports from other environments are welcome. Read CONTRIBUTING and SECURITY. Do not attach private papers, research notes, or model logs to public reports.

Code, documentation, the skill, and synthetic examples use the MIT License. Papers, datasets, and user-supplied material retain their own terms. See third-party notices for dependencies and brand assets for artwork.

About

Local research evidence CLI: connect paper claims to project decisions and export context for AI agents.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages