add CLI installation support and interactive graph visualization in UI

[AxelDlv00]

Overview

This PR introduces two major enhancements to the Archon project: a dedicated CLI installation workflow and a new graph visualization component within the user interface.

Changes

• The Repo has been restructured, the code is located in src/archon
• CLI & Installation:
  • The sh files from the base repository were replaced with python scripts
  • The installation and setup are now bundled into one single curl ... | bash command

Command	Description
init	Initialize a new Archon project.
loop	Start the automated formalization loop.
doctor	Verify the full Archon setup and health.
dashboard	Start the web monitoring interface.
prove	Directly prove an inline statement.
setup	Install required system dependencies.

• Integrated a new graph visualization in the ui/ directory.
• Updated README.md with instructions on how to use the new CLI features.

[littlebin530]

Review about setup.py:

1. Avoid silent sudo in archon setup

setup.py runs sudo apt-get install -y / sudo pacman -S --noconfirm without user confirmation when dependencies are missing. Consider either printing manual install instructions (as the old setup.sh did) or prompting the user before escalating to sudo.

2. Remove tmux from setup dependencies

tmux is checked and installed in setup.py as "required for parallel agent teams," but the actual parallelism in both the old archon-loop.sh (bash background processes) and the new loop.py (ProcessPoolExecutor) does not use tmux. It can be safely removed from the setup flow.

[littlebin530]

Review about init.py
How to plan for users in the current init to modify global or individual prompts/skills

Review about loop.py
We need to print some messages in the terminal, or directly launch the UI, to remind users to quickly check the results using the UI.

[littlebin530]

Review about init.py How to plan for users in the current init to modify global or individual prompts/skills

Review about loop.py We need to print some messages in the terminal, or directly launch the UI, to remind users to quickly check the results using the UI.

After chating with leheng, we have made some new discoveries and ideas.

1. The new version of Archon will report an error when trying to init a project that has already been initialized by the old version.
2. The old version of MCP has already been registered in Claude Code, reinitializing it may cause bugs.
3. We should start the dashboard directly in the loop
4. In the init phase, there is the conflict between the old and new prompts mentioned earlier. This can be helped by the part where Claude Code is called, allowing Claude Code to check what the differences are in each file, and then interact with the user to decide which version to keep. This should be more reasonable, as the user can make local changes, make global changes, or perform a merge during the init phase.

[AxelDlv00]

Review about setup.py:

1. Avoid silent sudo in archon setup

setup.py runs sudo apt-get install -y / sudo pacman -S --noconfirm without user confirmation when dependencies are missing. Consider either printing manual install instructions (as the old setup.sh did) or prompting the user before escalating to sudo.

2. Remove tmux from setup dependencies

tmux is checked and installed in setup.py as "required for parallel agent teams," but the actual parallelism in both the old archon-loop.sh (bash background processes) and the new loop.py (ProcessPoolExecutor) does not use tmux. It can be safely removed from the setup flow.

These two issues have been solved in commit #6bff60ab6daf5950c921b4cbb42e27e3ef53abef.
Now by default it prompts the user for confirmation before running a sudo command. (There is the possibility to use the option --yes to accept them automatically). Moreover, I completely removed tmux from the dependencies

[AxelDlv00]

Review about init.py How to plan for users in the current init to modify global or individual prompts/skills
Review about loop.py We need to print some messages in the terminal, or directly launch the UI, to remind users to quickly check the results using the UI.

After chating with leheng, we have made some new discoveries and ideas.

1. The new version of Archon will report an error when trying to init a project that has already been initialized by the old version.

2. The old version of MCP has already been registered in Claude Code, reinitializing it may cause bugs.

3. We should start the dashboard directly in the loop

4. In the init phase, there is the conflict between the old and new prompts mentioned earlier. This can be helped by the part where Claude Code is called, allowing Claude Code to check what the differences are in each file, and then interact with the user to decide which version to keep. This should be more reasonable, as the user can make local changes, make global changes, or perform a merge during the init phase.

Since the last commit (6bff60a) :

• Auto-Dashboard: The loop now automatically launches the dashboard on an available port (8080–8099). You can disable this with --no-dashboard or auto-open the browser with --open.
• UI Visibility: Added terminal reminders and panels that print the Dashboard URL at key stages.
• Legacy Detection: Existing setups are detected, it now handles legacy symlink layouts gracefully by prompting the user instead of crashing.
• Smart Reconciliation: If Claude Code is installed, init will launch a focused session to let the user diff and decide whether to keep local, take new, or merge changes per file. Otherwise the user can also directly choose to ovewrite everything/nothing
• MCP Conflict Resolution: The script now checks claude mcp list before registration. If archon-lean-lsp is already present, it skips re-registration to avoid breaking active sessions.

[AxelDlv00]

⚠⚠⚠⚠⚠ If the PR is accepted, please remember to modify "https://github.com/AxelDlv00/Archon/archive/refs/heads/main.tar.gz" in install.sh with "https://github.com/frenzymath/Archon/archive/refs/heads/main.tar.gz" ! Otherwise it will install from my fork. (I kept it like this right now to allow you to install it easily since "https://github.com/frenzymath/Archon/archive/refs/heads/main.tar.gz" doesn't exists yet.

In commit 6bff60a, I also added two minor changes.

• The prompt in init.md is modified to show "archon loop ..." and not "./archon_loop ..."
• There is a new command "archon update" to easily update the CLI, it doesn't launch any "archon init", therefore it warns the user that he may want to do so.

[littlebin530]

Review about init.py How to plan for users in the current init to modify global or individual prompts/skills
Review about loop.py We need to print some messages in the terminal, or directly launch the UI, to remind users to quickly check the results using the UI.

After chating with leheng, we have made some new discoveries and ideas.

1. The new version of Archon will report an error when trying to init a project that has already been initialized by the old version.

2. The old version of MCP has already been registered in Claude Code, reinitializing it may cause bugs.

3. We should start the dashboard directly in the loop

4. In the init phase, there is the conflict between the old and new prompts mentioned earlier. This can be helped by the part where Claude Code is called, allowing Claude Code to check what the differences are in each file, and then interact with the user to decide which version to keep. This should be more reasonable, as the user can make local changes, make global changes, or perform a merge during the init phase.

Since the last commit (6bff60a) :

• Auto-Dashboard: The loop now automatically launches the dashboard on an available port (8080–8099). You can disable this with --no-dashboard or auto-open the browser with --open.
• UI Visibility: Added terminal reminders and panels that print the Dashboard URL at key stages.
• Legacy Detection: Existing setups are detected, it now handles legacy symlink layouts gracefully by prompting the user instead of crashing.
• Smart Reconciliation: If Claude Code is installed, init will launch a focused session to let the user diff and decide whether to keep local, take new, or merge changes per file. Otherwise the user can also directly choose to ovewrite everything/nothing
• MCP Conflict Resolution: The script now checks claude mcp list before registration. If archon-lean-lsp is already present, it skips re-registration to avoid breaking active sessions.

There's one detail I'd like to confirm: regarding the MCP reinstallation, if the user has already registered for MCP, I think we should cancel the previous registration and use the new one. This is because the expectation is that the user should be able to delete the old Archon without data loss after installing the new version. If the old MCP is retained, it might cause the program to malfunction after the user deletes the old Archon folder.

[littlebin530]

⚠⚠⚠⚠⚠ If the PR is accepted, please remember to modify "https://github.com/AxelDlv00/Archon/archive/refs/heads/main.tar.gz" in install.sh with "https://github.com/frenzymath/Archon/archive/refs/heads/main.tar.gz" ! Otherwise it will install from my fork. (I kept it like this right now to allow you to install it easily since "https://github.com/frenzymath/Archon/archive/refs/heads/main.tar.gz" doesn't exists yet.

In commit 6bff60a, I also added two minor changes.

• The prompt in init.md is modified to show "archon loop ..." and not "./archon_loop ..."
• There is a new command "archon update" to easily update the CLI, it doesn't launch any "archon init", therefore it warns the user that he may want to do so.

I think a reasonable approach is for you to keep a copy of the PR that is exactly the same as your own fork, except for the download link. This way, we can use your code during testing, and once it passes review, we can directly approve the PR without needing to modify anything.

[AxelDlv00]

Review about init.py How to plan for users in the current init to modify global or individual prompts/skills
Review about loop.py We need to print some messages in the terminal, or directly launch the UI, to remind users to quickly check the results using the UI.

After chating with leheng, we have made some new discoveries and ideas.

1. The new version of Archon will report an error when trying to init a project that has already been initialized by the old version.

2. The old version of MCP has already been registered in Claude Code, reinitializing it may cause bugs.

3. We should start the dashboard directly in the loop

4. In the init phase, there is the conflict between the old and new prompts mentioned earlier. This can be helped by the part where Claude Code is called, allowing Claude Code to check what the differences are in each file, and then interact with the user to decide which version to keep. This should be more reasonable, as the user can make local changes, make global changes, or perform a merge during the init phase.

Since the last commit (6bff60a) :

• Auto-Dashboard: The loop now automatically launches the dashboard on an available port (8080–8099). You can disable this with --no-dashboard or auto-open the browser with --open.
• UI Visibility: Added terminal reminders and panels that print the Dashboard URL at key stages.
• Legacy Detection: Existing setups are detected, it now handles legacy symlink layouts gracefully by prompting the user instead of crashing.
• Smart Reconciliation: If Claude Code is installed, init will launch a focused session to let the user diff and decide whether to keep local, take new, or merge changes per file. Otherwise the user can also directly choose to ovewrite everything/nothing
• MCP Conflict Resolution: The script now checks claude mcp list before registration. If archon-lean-lsp is already present, it skips re-registration to avoid breaking active sessions.

There's one detail I'd like to confirm: regarding the MCP reinstallation, if the user has already registered for MCP, I think we should cancel the previous registration and use the new one. This is because the expectation is that the user should be able to delete the old Archon without data loss after installing the new version. If the old MCP is retained, it might cause the program to malfunction after the user deletes the old Archon folder.

You are correct, keeping the old registration would leave a dangling file path if the user decides to delete the old Archon folder. I've just updated the code to fix this. Now, if the script detects an existing archon-lean-lsp, it explicitly runs claude mcp remove to clear out the old path before re-registering it with the new one.

Regarding my last "⚠" about "https://github.com/frenzymath/Archon/archive/refs/heads/main.tar.gz", I eventually decided to set "frenzymath" because the previous installation file installs the main branch (on which I added other functionnalities), but this PR is on a distinct branch, sorry for the confusion. If you want to test the installation, just run "python3 -m pip install ." in the root directory if you cloned my code.

[littlebin530]

Remaining issues：

1. init.md last line — archon init <project_path> should be archon loop <project_path>, otherwise users will re-initialize instead of starting the loop.
2. init.py _step2_copy_prompts() — The fresh parameter is not used in the overwrite decision; existing prompts are preserved even when the user selects overwrite mode.
3. init.py _step1_state_dir() log.warn — The CLAUDE.md overwrite warning runs unconditionally, showing a misleading "will be overwritten" message even on first-time initialization.
4. init.py init() main function — After merge mode completes, execution falls through to step1, which overwrites CLAUDE.md with the bundled template and may clobber what Claude just merged.
5. loop.py _start_dashboard() + end of loop() — An atexit callback is registered to auto-kill the dashboard, but the final panel tells the user to stop it manually; the two behaviors contradict each other.
6. update.py update() subprocess.run — The curl URL still points to AxelDlv00/Archon; although install.sh was corrected to frenzymath, update.py was missed.

[AxelDlv00]

Remaining issues：

1. init.md last line — archon init <project_path> should be archon loop <project_path>, otherwise users will re-initialize instead of starting the loop.

2. init.py _step2_copy_prompts() — The fresh parameter is not used in the overwrite decision; existing prompts are preserved even when the user selects overwrite mode.

3. init.py _step1_state_dir() log.warn — The CLAUDE.md overwrite warning runs unconditionally, showing a misleading "will be overwritten" message even on first-time initialization.

4. init.py init() main function — After merge mode completes, execution falls through to step1, which overwrites CLAUDE.md with the bundled template and may clobber what Claude just merged.

5. loop.py _start_dashboard() + end of loop() — An atexit callback is registered to auto-kill the dashboard, but the final panel tells the user to stop it manually; the two behaviors contradict each other.

6. update.py update() subprocess.run — The curl URL still points to AxelDlv00/Archon; although install.sh was corrected to frenzymath, update.py was missed.

Changes

I modified the files to answer your catches.

update.py : fix installer URL

The archon update command is now curling frenzymath/Archon.

prompts/init.md — fix next-step hint

The final line is corrected to archon loop <project_path>.

init.py — re-init flow correctness

Three related bugs in the re-init path:

1. "will be overwritten" warning on fresh installs. The warning now only fires when CLAUDE.md actually exists and is about to be replaced.

2. Merge mode clobbered its own work.

• Adding a refresh_claude_md: bool parameter to _step1_state_dir.
• Setting merged_claude_md = True in init() after a successful merge run.
• Passing refresh_claude_md=not merged_claude_md into step1.

A safety net copies CLAUDE.md from the template if it's somehow missing after a merge, but never overwrites an existing one.

3. _step2_copy_prompts ignored the fresh parameter.

• fresh=True (first init or "overwrite" mode): replace existing prompts with bundled versions, log how many were overwritten.
• fresh=False (re-init after merge): preserve local edits (reconciliation already happened in the merge step).
• Stale symlinks from the legacy layout are always replaced, regardless of fresh, since a broken symlink is never correct.

loop.py — dashboard lifecycle

The dashboard now persists after the loop so results can be reviewed and I removed the atexit hook.

• Ctrl-C / kill still tears down the dashboard process group cleanly.
• Normal completion leaves the dashboard running, matching what the panel promises.
• Previous signal handlers are restored on exit, so calling loop() from a larger Python program doesn't leak handlers into global state.
• Handler installation is guarded against ValueError / OSError for cases where we're not in the main thread or the platform doesn't support it.

[littlebin530]

The rollback instruction git checkout .archon/ in MIGRATION.md is invalid because .archon/ is in .gitignore and was never tracked by git; maybe it should be replaced with cp -r .archon .archon.bak for manual backup.

[AxelDlv00]

The rollback instruction git checkout .archon/ in MIGRATION.md is invalid because .archon/ is in .gitignore and was never tracked by git; maybe it should be replaced with cp -r .archon .archon.bak for manual backup.

Indeed, I modified with a copy from a backup as suggested.