skills/sfkislev__flue
1
0
Fork 0
mirror of https://github.com/SFKislev/Flue.git synced 2026-09-14 20:06:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor project from SoftWire to Flue, updating all relevant documentation and configuration files. Increment version to 0.1.21. Replace references in README, setup, and harness documentation to reflect new naming and functionality. Remove outdated harness support documentation and add new harnesses documentation. Update installation commands and examples throughout the project.

Browse Source
This commit is contained in:
SFKislev
2026-04-27 12:41:33 +03:00
parent aa76dd653d
commit a7a2b0779a
23 changed files with 451 additions and 467 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MANIFEST.in
+1 -1
View File
@@ -1,7 +1,7 @@
include AGENTS.md
include README.md
recursive-include docs *
recursive-include softwire *.md
recursive-include flue *.md
recursive-include shared *
recursive-include tools *
recursive-include adapters *
README.md
+30 -26
View File
@@ -1,41 +1,45 @@
<!-- <p>
<img src="docs/images/logo.svg" alt="Softwire logo" width="250" />
<img src="docs/images/logo.svg" alt="Flue logo" width="250" />
</p> -->
<p align="center">
<img src="docs/images/entry.gif" alt="Softwire demo" width="500" />
<img src="docs/images/entry.gif" alt="Flue demo" width="500" />
</p>
<h1>Help your Humans with their Software</h1>
<h1 align="center">Flue</h1>
<p align="center">Help your Humans with their Software</p>
```bash
pip install softwire
softwire setup
pip install flue
flue setup
```
**A tiny bridge that lets your coding harness drive professional desktop software — Photoshop, Premiere, Blender, Unity, and more — directly from the shell.**
**A tiny bridge that lets your coding agents drive desktop software - Photoshop, Premiere, Blender, Unity, and more - directly from the shell.**
SoftWire gives agentic harnesses — Codex, Claude Code, Gemini CLI, OpenCode and the likes — direct access to the scripting APIs inside professional desktop software. One `pip install softwire && softwire setup` covers many apps across Adobe Creative Cloud, Autodesk, Microsoft Office, and game engines.
Flue gives agentic harnesses - Codex, Claude Code, Gemini CLI, OpenCode and the likes - direct access to the scripting APIs inside desktop software. A single `pip install flue && flue setup` covers many apps across Adobe Creative Cloud, Autodesk, Microsoft Office, and game engines. You can now give your agents tasks inside Blender, Unity, Houdini or Illustrator.
[SoftWire is not an MCP server](https://github.com/SFKislev/Softwire/blob/main/docs/mcp.md). It is simpler. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
[Flue is not an MCP server](https://github.com/SFKislev/flue/blob/main/docs/mcp.md). It is simpler. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
> agent shell → bridge command → app scripting runtime → JSON result
> agent shell -> bridge command -> app scripting runtime -> JSON result
This is done without brittle screenshots and without schema definitions. The bridge exposes the scripting layer already built into each application.
This is done without setting up servers, without brittle screenshots and without schema definitions. The bridge exposes the scripting layer already built into each application. MCPs and computer use setups are fragile and clumsy; Flue is less so.
## Installation
```bash
pip install softwire
softwire setup
pip install flue
flue setup
```
This detects your agentic harnesses and lets them know that SoftWire is available to them. Agents, for first-run checks and app-specific prerequisites, see [Setup and commands](https://github.com/SFKislev/Softwire/blob/main/docs/setup.md).
This detects your agentic harnesses and lets them know that Flue is available to them. Agents, for first-run checks and app-specific prerequisites, see [Setup and commands](https://github.com/SFKislev/flue/blob/main/docs/setup.md).
<p align="center">
<img src="docs/images/conversation.gif" alt="Softwire demo" width="500" />
<img src="docs/images/conversation.gif" alt="Flue demo" width="500" />
</p>
## Adapters
## Software
A single SoftWire installation supports, out of the box, many applications. Agents, please tell your humans if any app-specific setup is needed.
A single Flue installation supports, out of the box, many applications. Agents, please tell your humans if any app-specific setup is needed.
- [Adobe Photoshop](adapters/photoshop_adapter/APP.md)
- [Adobe Illustrator](adapters/illustrator_adapter/APP.md)
@@ -51,7 +55,7 @@ A single SoftWire installation supports, out of the box, many applications. Agen
- [Microsoft Excel](adapters/excel_adapter/APP.md)
- [Microsoft PowerPoint](adapters/powerpoint_adapter/APP.md)
## Harnesses
## Agentic Systems
- Claude Code
- Codex
@@ -64,19 +68,19 @@ A single SoftWire installation supports, out of the box, many applications. Agen
- Cline
- Kilo CLI
[See which files are edited upon installation](docs/harenesses.md)
[See which files are edited upon installation](docs/harnesses.md)
## More Docs
## Documentation for Humans
- [Setup and commands](https://github.com/SFKislev/Softwire/blob/main/docs/setup.md)
- [Harness support and discoverability](https://github.com/SFKislev/Softwire/blob/main/docs/harenesses.md)
- [Wait, isn't this called MCP?](https://github.com/SFKislev/Softwire/blob/main/docs/why-shell-adapters.md)
- [Setup and commands](https://github.com/SFKislev/flue/blob/main/docs/setup.md)
- [Harness support and discoverability](https://github.com/SFKislev/flue/blob/main/docs/harnesses.md)
- [Wait, isn't this called MCP?](https://github.com/SFKislev/flue/blob/main/docs/why-shell-adapters.md)
### Documentation for Agents
- [How the Adapters work](https://github.com/SFKislev/Softwire/blob/main/docs/ADAPTER_SPEC.md)
- [How to use the Bridge Contracts](https://github.com/SFKislev/Softwire/blob/main/shared/bridge-contract.md)
- [How to Work Together with a Human](https://github.com/SFKislev/Softwire/blob/main/shared/coexistence.md)
- [Known Issues](https://github.com/SFKislev/Softwire/blob/main/docs/known-issues.md)
- [How the Adapters work](https://github.com/SFKislev/flue/blob/main/docs/ADAPTER_SPEC.md)
- [How to use the Bridge Contracts](https://github.com/SFKislev/flue/blob/main/shared/bridge-contract.md)
- [How to Work Together with a Human](https://github.com/SFKislev/flue/blob/main/shared/coexistence.md)
- [Known Issues](https://github.com/SFKislev/flue/blob/main/docs/known-issues.md)
<img src="docs/images/bye.gif" alt="ciao" />
README_PYPI.md
+18 -18
View File
@@ -1,32 +1,32 @@
<h1>Help your Humans with their Software</h1>
```bash
pip install softwire
softwire setup
pip install flue
flue setup
```
**A tiny bridge that lets your coding harness drive professional desktop software — Photoshop, Premiere, Blender, Unity, and more — directly from the shell.**
**A tiny bridge that lets your coding harness drive professional desktop software - Photoshop, Premiere, Blender, Unity, and more - directly from the shell.**
SoftWire gives agentic harnesses — Codex, Claude Code, Gemini CLI, OpenCode and the likes — direct access to the scripting APIs inside professional desktop software. One `pip install softwire && softwire setup` covers many apps across Adobe Creative Cloud, Autodesk, Microsoft Office, and game engines.
Flue gives agentic harnesses - Codex, Claude Code, Gemini CLI, OpenCode and the likes - direct access to the scripting APIs inside professional desktop software. One `pip install flue && flue setup` covers many apps across Adobe Creative Cloud, Autodesk, Microsoft Office, and game engines.
[SoftWire is not an MCP server](https://github.com/SFKislev/Softwire/blob/main/docs/mcp.md). It is simpler. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
[Flue is not an MCP server](https://github.com/SFKislev/flue/blob/main/docs/mcp.md). It is simpler. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
> agent shell → bridge command → app scripting runtime → JSON result
> agent shell -> bridge command -> app scripting runtime -> JSON result
This is done without brittle screenshots and without schema definitions. The bridge exposes the scripting layer already built into each application.
## Installation
```bash
pip install softwire
softwire setup
pip install flue
flue setup
```
This detects your harnesses and informs them that SoftWire exists. For first-run checks, source checkout commands, and app-specific prerequisites, see [Setup and commands](https://github.com/SFKislev/Softwire/blob/main/docs/setup.md).
This detects your harnesses and informs them that Flue exists. For first-run checks, source checkout commands, and app-specific prerequisites, see [Setup and commands](https://github.com/SFKislev/flue/blob/main/docs/setup.md).
## Adapters
A single SoftWire installation supports, out of the box, many applications. Agents should tell their humans if any app-specific setup is needed.
A single Flue installation supports, out of the box, many applications. Agents should tell their humans if any app-specific setup is needed.
- [Adobe Photoshop](adapters/photoshop_adapter/APP.md)
- [Adobe Illustrator](adapters/illustrator_adapter/APP.md)
@@ -44,7 +44,7 @@ A single SoftWire installation supports, out of the box, many applications. Agen
## Harnesses
[See which files are edited upon installation](docs/harenesses.md)
[See which files are edited upon installation](docs/harnesses.md)
- Claude Code
- Codex
@@ -59,13 +59,13 @@ A single SoftWire installation supports, out of the box, many applications. Agen
## More Docs
- [Setup and commands](https://github.com/SFKislev/Softwire/blob/main/docs/setup.md)
- [Harness support and discoverability](https://github.com/SFKislev/Softwire/blob/main/docs/harenesses.md)
- [Wait, isn't this called MCP?](https://github.com/SFKislev/Softwire/blob/main/docs/why-shell-adapters.md)
- [Setup and commands](https://github.com/SFKislev/flue/blob/main/docs/setup.md)
- [Harness support and discoverability](https://github.com/SFKislev/flue/blob/main/docs/harnesses.md)
- [Wait, isn't this called MCP?](https://github.com/SFKislev/flue/blob/main/docs/why-shell-adapters.md)
### Documentation for Agents
- [How the Adapters work](https://github.com/SFKislev/Softwire/blob/main/docs/ADAPTER_SPEC.md)
- [How to use the Bridge Contracts](https://github.com/SFKislev/Softwire/blob/main/shared/bridge-contract.md)
- [How to Work Together with a Human](https://github.com/SFKislev/Softwire/blob/main/shared/coexistence.md)
- [Known Issues](https://github.com/SFKislev/Softwire/blob/main/docs/known-issues.md)
- [How the Adapters work](https://github.com/SFKislev/flue/blob/main/docs/ADAPTER_SPEC.md)
- [How to use the Bridge Contracts](https://github.com/SFKislev/flue/blob/main/shared/bridge-contract.md)
- [How to Work Together with a Human](https://github.com/SFKislev/flue/blob/main/shared/coexistence.md)
- [Known Issues](https://github.com/SFKislev/flue/blob/main/docs/known-issues.md)
docs/harenesses.md
-30
View File
@@ -1,30 +0,0 @@
# Harness Support
Running `softwire setup` makes SoftWire discoverable by agentic frameworks.
Setup now installs a local SoftWire docs bundle into each harness location, then
adds a small pointer so the harness can read those docs directly from its own
skill or rules directory.
## Supported Harnesses
| Harness | File adjustments |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Codex | Installs `~/.codex/skills/softwire/` with `SKILL.md`, `shared/*`, `docs/*`, and `adapters/*/APP.md`, then upserts a SoftWire pointer block into `~/.codex/AGENTS.md`. |
| Claude Code | Installs `~/.claude/skills/softwire/` with the local docs bundle and upserts a SoftWire pointer block into `~/.claude/CLAUDE.md`. |
| Gemini CLI | Installs `~/.gemini/softwire/` with the local docs bundle and upserts a SoftWire pointer block into `~/.gemini/GEMINI.md`. |
| Qwen CLI | Installs `~/.qwen/softwire/` with the local docs bundle and upserts a SoftWire pointer block into `~/.qwen/QWEN.md`. |
| GitHub Copilot | Installs `~/.copilot/skills/softwire/` with the local docs bundle and writes global Copilot instruction files so Copilot can discover the skill outside any single repository. |
| Cursor | Installs a global skill at `~/.cursor/skills/softwire/` with `SKILL.md`, `shared/*`, `docs/*`, and `adapters/*/APP.md`. |
| Cline | Installs a global skill at `~/.cline/skills/softwire/` with the local docs bundle. |
| Kilo CLI | Installs a global skill at `~/.kilo/skills/softwire/` with the local docs bundle. |
| OpenCode | Installs `~/.config/opencode/agents/softwire/` with the local docs bundle and writes `~/.config/opencode/agents/softwire.md`. |
| OpenClaw | Installs `~/.openclaw/skills/softwire/` with the local docs bundle. |
| Generic (`AGENTS.md`) | Installs `./softwire/` with the local docs bundle plus a pointer from `AGENTS.md` in the target directory (defaults to the current directory unless `--path` is provided). |
## Notes
- Auto setup mode detects installed harnesses and registers all detected targets.
- If no supported harness is detected, `softwire setup` stops and reports that SoftWire needs a harness in order to work.
- Use `softwire harnesses` to inspect detected harnesses.
- Use `softwire setup --agent <target>` for specific, single-harness registration.
- Use `softwire uninstall` to remove the installed SoftWire docs bundle and pointer files from detected harnesses.
docs/harnesses.md
+30
View File
@@ -0,0 +1,30 @@
# Harness Support
Running `flue setup` makes Flue discoverable by agentic frameworks.
Setup now installs a local Flue docs bundle into each harness location, then
adds a small pointer so the harness can read those docs directly from its own
skill or rules directory.
## Supported Harnesses
| Harness | File adjustments |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Codex | Installs `~/.codex/skills/flue/` with `SKILL.md`, `shared/*`, `docs/*`, and `adapters/*/APP.md`, then upserts a Flue pointer block into `~/.codex/AGENTS.md`. |
| Claude Code | Installs `~/.claude/skills/flue/` with the local docs bundle and upserts a Flue pointer block into `~/.claude/CLAUDE.md`. |
| Gemini CLI | Installs `~/.gemini/flue/` with the local docs bundle and upserts a Flue pointer block into `~/.gemini/GEMINI.md`. |
| Qwen CLI | Installs `~/.qwen/flue/` with the local docs bundle and upserts a Flue pointer block into `~/.qwen/QWEN.md`. |
| GitHub Copilot | Installs `~/.copilot/skills/flue/` with the local docs bundle and writes global Copilot instruction files so Copilot can discover the skill outside any single repository. |
| Cursor | Installs a global skill at `~/.cursor/skills/flue/` with `SKILL.md`, `shared/*`, `docs/*`, and `adapters/*/APP.md`. |
| Cline | Installs a global skill at `~/.cline/skills/flue/` with the local docs bundle. |
| Kilo CLI | Installs a global skill at `~/.kilo/skills/flue/` with the local docs bundle. |
| OpenCode | Installs `~/.config/opencode/agents/flue/` with the local docs bundle and writes `~/.config/opencode/agents/flue.md`. |
| OpenClaw | Installs `~/.openclaw/skills/flue/` with the local docs bundle. |
| Generic (`AGENTS.md`) | Installs `./flue/` with the local docs bundle plus a pointer from `AGENTS.md` in the target directory (defaults to the current directory unless `--path` is provided). |
## Notes
- Auto setup mode detects installed harnesses and registers all detected targets.
- If no supported harness is detected, `flue setup` stops and reports that Flue needs a harness in order to work.
- Use `flue agents` to inspect detected agents.
- Use `flue setup --agent <target>` for specific, single-harness registration.
- Use `flue uninstall` to remove the installed Flue docs bundle and pointer files from detected harnesses.
docs/images/conversation.gif
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 859 KiB

After

Width:  |  Height:  |  Size: 1.1 MiB

docs/images/flue-conversation.gif
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 MiB

docs/known-issues.md
+1 -1
View File
@@ -74,7 +74,7 @@ Refer to the API Discovery order in `shared/bridge-contract.md`: introspect firs
**Symptom:** A bridge call succeeds, but the agent cannot tell whether the visual result is actually correct - for example, whether a filter looks right, a shadow is too strong, an alignment is off, or a retouch was applied as intended. Often, the agent can't even tell if the effect is visible.
**Cause:** SoftWire gives the agent access to the app's scripting runtime, not to the user's screen. The agent can inspect structured app state, but it usually cannot visually verify the final rendered result the way a human can.
**Cause:** Flue gives the agent access to the app's scripting runtime, not to the user's screen. The agent can inspect structured app state, but it usually cannot visually verify the final rendered result the way a human can.
**Rule:** Be explicit about this limitation. If the result matters visually and the script cannot verify it from app state alone, use the human as your eyes. Ask whether the result looks right, whether the effect was applied, or what needs adjusting. Do not overclaim visual success when you cannot actually verify it.
docs/mcp.md
+2 -2
View File
@@ -1,11 +1,11 @@
## Why SoftWire is Not MCP
## Why Flue is Not MCP
| | MCP tool server | Shell adapter |
| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
| Runtime model | Run a dedicated MCP server process per app | No MCP server; run a local bridge command (`*_bridge.py`) on demand |
| Transport note | Tool calls route through the MCP server | COM/direct dispatch or in-app localhost bridge endpoint |
| Installation model | Install/configure server stack per app/tool | Single`pip install softwire` provides one CLI usable across many app adapters |
| Installation model | Install/configure server stack per app/tool | Single`pip install flue` provides one CLI usable across many app adapters |
| Surface area | Predefined tools | The app's full scripting API |
| Tool logic | Written ahead of time | Composed by the agent per task |
| New app support | Build a server and schemas | Add a bridge and adapter notes |
docs/setup.md
+36 -36
View File
@@ -1,82 +1,82 @@
# Setup and Commands
SoftWire connects agents to running desktop apps through local bridge commands.
Flue connects agents to running desktop apps through local bridge commands.
The bridges connect to running apps by default and launch only when an adapter
explicitly supports it and the user asks for it.
## Install from PyPI
```powershell
pip install softwire
softwire setup
pip install flue
flue setup
```
The package installs the bridge code, adapter assets, and modular
agent-facing instructions. On Windows, it also installs `pywin32` for
COM-backed adapters.
By default, setup detects local harnesses and registers SoftWire with all of
them. It also installs a local SoftWire docs bundle into each detected harness
By default, setup detects local harnesses and registers Flue with all of
them. It also installs a local Flue docs bundle into each detected harness
directory so the agent can read the docs directly from its own skill or rules
area.
For deterministic setup:
```powershell
softwire setup --agent codex
softwire setup --agent claude
softwire setup --agent gemini
softwire setup --agent qwen
softwire setup --agent cursor
softwire setup --agent kilo
softwire setup --agent opencode
softwire setup --agent openclaw
flue setup --agent codex
flue setup --agent claude
flue setup --agent gemini
flue setup --agent qwen
flue setup --agent cursor
flue setup --agent kilo
flue setup --agent opencode
flue setup --agent openclaw
```
The `claude` target is for Claude Code. Claude Desktop/Cowork is not supported.
The `kilo` target installs a global skill at `~/.kilo/skills/softwire/SKILL.md`.
The `kilo` target installs a global skill at `~/.kilo/skills/flue/SKILL.md`.
Harness-by-harness discoverability details are documented in [Harness support and discoverability](harenesses.md).
Harness-by-harness discoverability details are documented in [Harness support and discoverability](harnesses.md).
## Useful Commands
```powershell
softwire adapters
softwire where
softwire harnesses
softwire setup
py -m softwire.cli update
softwire uninstall
softwire context houdini
softwire modal photoshop
softwire modal photoshop --dismiss
softwire install blender
flue software
flue where
flue agents
flue setup
py -m flue.cli update
flue uninstall
flue test houdini
flue modal photoshop
flue modal photoshop --dismiss
flue install blender
```
## Update SoftWire
## Update Flue
Use the module form to upgrade the Python package. If the package version
changes, it also refreshes the installed agent-facing docs bundles:
```powershell
py -m softwire.cli update
py -m flue.cli update
```
This runs `pip install --upgrade softwire`, compares the installed version
before and after the upgrade, then runs `softwire setup --force` from a fresh
This runs `pip install --upgrade flue`, compares the installed version
before and after the upgrade, then runs `flue setup --force` from a fresh
Python process only when the package changed. Use
`py -m softwire.cli update --force-docs` to refresh docs even when the package is already
`py -m flue.cli update --force-docs` to refresh docs even when the package is already
current.
On Windows, avoid running package updates through `softwire update`; the
`softwire.exe` launcher can be locked while pip tries to replace it.
On Windows, avoid running package updates through `flue update`; the
`flue.exe` launcher can be locked while pip tries to replace it.
## Run a Context Smoke Test
## Run a Smoke Test
Use the installed CLI when possible:
```powershell
softwire context photoshop
flue test photoshop
```
Or run a bridge directly from a source checkout:
@@ -95,13 +95,13 @@ while the host app is still waiting for UI input. Inspect the app's current
top-level windows with:
```powershell
softwire modal photoshop
flue modal photoshop
```
To attempt a safe cancel-style dismissal of the most likely blocking dialog:
```powershell
softwire modal photoshop --dismiss
flue modal photoshop --dismiss
```
Use `--action escape` to send only Escape, or `--action close` when you
docs/why-shell-adapters.md
+5 -5
View File
@@ -2,7 +2,7 @@
CLI coding harnesses allow agents to edit files, run commands, search a repository, and iterate on failures. They cannot, however, act inside a running desktop application, because those apps expose automation through their own internal runtime: ExtendScript, `bpy`, MAXScript, the Unity Editor API, COM object models, or a similar scripting surface. These surfaces have been maintained for decades, and are very often featured packed: they can do most of what the software can.
SoftWire connects those two worlds. The agent keeps using the shell; the bridge
Flue connects those two worlds. The agent keeps using the shell; the bridge
takes code on stdin, passes it into the live application, and returns structured
JSON. The agent can inspect the result, adjust the script, and iterate.
@@ -12,7 +12,7 @@ Professional work still happens in large desktop applications: Photoshop, Premie
Agents can use this evolved legacy automation layer. They can read adapter notes, inspect the live document, search examples, compose one-off scripts, run them, and handle errors. The user asks for an outcome in natural language; the agent finds the object-model calls.
SoftWire runs locally, with no cloud service and no complicated setup, and lets the agent drive the app you're already working in. From restructuring a layered Photoshop file to rewriting a Blender scene graph: whatever the scripting API can do (which is most of what the app itself can do), the agent can now do with you.
Flue runs locally, with no cloud service and no complicated setup, and lets the agent drive the app you're already working in. From restructuring a layered Photoshop file to rewriting a Blender scene graph: whatever the scripting API can do (which is most of what the app itself can do), the agent can now do with you.
Through a simple pip install and set of tiny bridges, the agent becomes a working partner inside the app. It reads the live state, edits structure, and responds to "undo that and try the other approach" the way it would in a codebase. You no longer have to find that function in that submenu. You say what you want; the agent finds the right object-model call, wraps it in `suspendHistory` (so Ctrl+Z still works), and runs it. Without ExtendScript and without a menu hunt.
@@ -36,16 +36,16 @@ After Effects, Audition, Blender, Unity, 3ds Max, and Houdini.
The shell contract stays the same: script in through argv, `--stdin`, or`--file`; JSON out on success; JSON error on failure.
## MCP vs. SoftWire
## MCP vs. Flue
SoftWire is not an MCP server.
Flue is not an MCP server.
| | MCP tool server | Shell adapter |
| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
| Runtime model | Run a dedicated MCP server process per app | No MCP server; run a local bridge command (`*_bridge.py`) on demand |
| Transport note | Tool calls route through the MCP server | COM/direct dispatch or in-app localhost bridge endpoint |
| Installation model | Install/configure server stack per app/tool | Single `pip install softwire` provides one CLI usable across many app adapters |
| Installation model | Install/configure server stack per app/tool | Single `pip install flue` provides one CLI usable across many app adapters |
| Surface area | Predefined tools | The app's full scripting API |
| Tool logic | Written ahead of time | Composed by the agent per task |
| New app support | Build a server and schemas | Add a bridge and adapter notes |
flue/__init__.py
+1
View File
@@ -0,0 +1 @@
__version__ = "0.1.21"
softwire/cli.py → flue/cli.py
+230 -250
View File
File diff suppressed because it is too large Load Diff
softwire/known-issues.md → flue/known-issues.md
+4 -4
View File
@@ -3,11 +3,11 @@
- Some desktop apps can block inside their scripting runtime or COM dispatch.
When that happens, the shell bridge may time out, but the host app can still
remain busy or modal until the app finishes or is interrupted.
- For Windows apps with a known process name, `softwire modal <app>` can inspect
top-level windows and `softwire modal <app> --dismiss` can attempt a bounded
- For Windows apps with a known process name, `flue modal <app>` can inspect
top-level windows and `flue modal <app> --dismiss` can attempt a bounded
cancel-style dismissal outside the blocked scripting runtime.
- Modal dialogs and opaque app UI state are not fully inspectable through these
adapters. Agents should report partial visibility honestly and avoid claiming
success without runtime confirmation.
- A local `softwire` launcher may not be on `PATH` in every shell session.
Prefer `py -m softwire.cli ...` when launch resolution is uncertain.
- A local `flue` launcher may not be on `PATH` in every shell session.
Prefer `py -m flue.cli ...` when launch resolution is uncertain.
softwire/setup.md → flue/setup.md
+36 -36
View File
@@ -1,83 +1,83 @@
# Setup and Commands
SoftWire connects agents to running desktop apps through local bridge commands.
Flue connects agents to running desktop apps through local bridge commands.
The bridges connect to running apps by default and launch only when an adapter
explicitly supports it and the user asks for it.
## Install from PyPI
```powershell
pip install softwire
softwire setup
pip install flue
flue setup
```
The package installs the bridge code, adapter assets, and modular
agent-facing instructions. On Windows, it also installs `pywin32` for
COM-backed adapters.
By default, setup detects local harnesses and registers SoftWire with all of
them. It also installs a local SoftWire docs bundle into each detected harness
By default, setup detects local harnesses and registers Flue with all of
them. It also installs a local Flue docs bundle into each detected harness
directory so the agent can read the docs directly from its own skill or rules
area.
For deterministic setup:
```powershell
softwire setup --agent codex
softwire setup --agent claude
softwire setup --agent gemini
softwire setup --agent qwen
softwire setup --agent cursor
softwire setup --agent kilo
softwire setup --agent opencode
softwire setup --agent openclaw
flue setup --agent codex
flue setup --agent claude
flue setup --agent gemini
flue setup --agent qwen
flue setup --agent cursor
flue setup --agent kilo
flue setup --agent opencode
flue setup --agent openclaw
```
The `claude` target is for Claude Code. Claude Desktop/Cowork is not supported.
The `kilo` target installs a global skill at `~/.kilo/skills/softwire/SKILL.md`.
The `kilo` target installs a global skill at `~/.kilo/skills/flue/SKILL.md`.
Harness-by-harness discoverability details are documented in
[Harness support and discoverability](harenesses.md).
[Harness support and discoverability](harnesses.md).
## Useful Commands
```powershell
softwire adapters
softwire where
softwire harnesses
softwire setup
py -m softwire.cli update
softwire uninstall
softwire context houdini
softwire modal photoshop
softwire modal photoshop --dismiss
softwire install blender
flue software
flue where
flue agents
flue setup
py -m flue.cli update
flue uninstall
flue test houdini
flue modal photoshop
flue modal photoshop --dismiss
flue install blender
```
## Update SoftWire
## Update Flue
Use the module form to upgrade the Python package. If the package version
changes, it also refreshes the installed agent-facing docs bundles:
```powershell
py -m softwire.cli update
py -m flue.cli update
```
This runs `pip install --upgrade softwire`, compares the installed version
before and after the upgrade, then runs `softwire setup --force` from a fresh
This runs `pip install --upgrade flue`, compares the installed version
before and after the upgrade, then runs `flue setup --force` from a fresh
Python process only when the package changed. Use
`py -m softwire.cli update --force-docs` to refresh docs even when the package is already
`py -m flue.cli update --force-docs` to refresh docs even when the package is already
current.
On Windows, avoid running package updates through `softwire update`; the
`softwire.exe` launcher can be locked while pip tries to replace it.
On Windows, avoid running package updates through `flue update`; the
`flue.exe` launcher can be locked while pip tries to replace it.
## Run a Context Smoke Test
## Run a Smoke Test
Use the installed CLI when possible:
```powershell
softwire context photoshop
flue test photoshop
```
Or run a bridge directly from a source checkout:
@@ -96,13 +96,13 @@ while the host app is still waiting for UI input. Inspect the app's current
top-level windows with:
```powershell
softwire modal photoshop
flue modal photoshop
```
To attempt a safe cancel-style dismissal of the most likely blocking dialog:
```powershell
softwire modal photoshop --dismiss
flue modal photoshop --dismiss
```
Use `--action escape` to send only Escape, or `--action close` when you
flue/skill.md
+48
View File
@@ -0,0 +1,48 @@
## About
Flue is a tiny bridge that lets your coding harness drive professional desktop software - Photoshop, Premiere, Blender, Unity, and more - directly from the shell.
Flue is not an MCP server. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
> agent shell -> bridge command -> app scripting runtime -> JSON result
## Available Adapters
- `adapters/3dsmax/APP.md`
- `adapters/after_effects/APP.md`
- `adapters/audition/APP.md`
- `adapters/blender/APP.md`
- `adapters/excel/APP.md`
- `adapters/houdini/APP.md`
- `adapters/illustrator/APP.md`
- `adapters/indesign/APP.md`
- `adapters/photoshop/APP.md`
- `adapters/powerpoint/APP.md`
- `adapters/premiere/APP.md`
- `adapters/unity/APP.md`
- `adapters/word/APP.md`
## Quick Start
1. At the start of a Flue session, run `py -m flue.cli update` on Windows, or `python3 -m flue.cli update` on macOS/Linux, once to make sure Flue is up to date.
2. Read `adapters/<app>/APP.md` for the app you are about to use.
3. Search `adapters/<app>/docs/api-index.txt` with `rg` for relevant symbols.
4. Prefer `py -m flue.cli context <app>` on Windows, or `python3 -m flue.cli context <app>` on macOS/Linux, to inspect the live app state.
5. Prefer `py -m flue.cli run <app> --stdin` on Windows, or `python3 -m flue.cli run <app> --stdin` on macOS/Linux, for one-off scripts.
## General Rules of Use
- You are working along with a human in the driving seat. Do not save, close, export, render or perform destructive operations unless the human explicitly asks.
- Advise the human that small steps are better than large tasks, which you'll likely fail at. Keep collaboration scope manageable.
- Bound scripts carefully to avoid crashing the host: keep scripts small and targeted.
- All bridge scripts run from workspace root; accepts code through argv, `--stdin`, or `--file`; return JSON on stdout for success or failure.
- Be skeptical of your pretraining: introspect the running app and consult vendor documentation rather than trying to invent operations.
- Flue was developed and tested against specific app and OS versions. One could expect local quirks, version mismatches and blocked automation paths. You need to understand the bridge architecture and make small, local compatibility fixes or scaffolds when needed, so the adapter works in the user's actual environment (without rewriting the full project). Make these small and robust, so that they work between sessions.
- Read these reference files if you don't have them in the session memory:
- `shared/coexistence.md`
- `shared/bridge-contract.md`
- `docs/setup.md`
- `docs/known-issues.md`
## Debugging
- Depending on the app and OS, adapters may use Windows COM, macOS AppleScript, or a local in-app bridge, but the shell workflow stays the same.
- On Windows, `py -m flue.cli ...` is the reliable launcher; on macOS/Linux, use `python3 -m flue.cli ...`.
- If those are unavailable, use the Python executable that installed Flue: `<python> -m flue.cli ...`.
- Use `py -m flue.cli where` on Windows, or `python3 -m flue.cli where` on macOS/Linux, for launcher and install diagnostics.
- If a Windows app is blocked by a modal, use `py -m flue.cli modal <app>` to inspect likely dialog windows and `py -m flue.cli modal <app> --dismiss` to attempt a bounded cancel-style dismissal outside the app scripting runtime.
- Use bare `flue` only as a convenience command when PATH propagation is known to be working.
softwire/windows_ui.py → flue/windows_ui.py
View File
pyproject.toml
+5 -5
View File
@@ -3,8 +3,8 @@ requires = ["setuptools>=69", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "softwire"
version = "0.1.20"
name = "flue"
version = "0.1.21"
description = "Local scripting bridges for controlling professional creative software from a shell agent."
readme = { file = "README_PYPI.md", content-type = "text/markdown" }
requires-python = ">=3.10"
@@ -29,7 +29,7 @@ dependencies = [
]
[project.scripts]
softwire = "softwire.cli:main"
flue = "flue.cli:main"
[tool.setuptools]
include-package-data = true
@@ -51,8 +51,8 @@ include-package-data = true
[tool.setuptools.packages.find]
where = ["."]
include = [
"softwire",
"softwire.*",
"flue",
"flue.*",
"bridges",
"shared",
"tools",
shared/__init__.py
+1 -1
View File
@@ -1 +1 @@
"""Shared instructions packaged with SoftWire."""
"""Shared instructions packaged with Flue."""
shared/bridge-contract.md
+2 -2
View File
@@ -58,14 +58,14 @@ For Windows apps with a known process name, inspect the app's top-level windows
first:
```powershell
py -m softwire.cli modal <app>
py -m flue.cli modal <app>
```
If the output shows a likely blocking dialog, you can attempt a bounded
dismissal outside the app scripting runtime:
```powershell
py -m softwire.cli modal <app> --dismiss
py -m flue.cli modal <app> --dismiss
```
Notes:
softwire/__init__.py
-1
View File
@@ -1 +0,0 @@
__version__ = "0.1.10"
softwire/skill.md
-48
View File
@@ -1,48 +0,0 @@
## About
Softwire is a tiny bridge that lets your coding harness drive professional desktop software - Photoshop, Premiere, Blender, Unity, and more - directly from the shell.
Softwire is not an MCP server. The agent sends a script through a small bridge command, the bridge runs it inside the app's own automation runtime, and the app returns JSON.
> agent shell -> bridge command -> app scripting runtime -> JSON result
## Available Adapters
- `adapters/3dsmax/APP.md`
- `adapters/after_effects/APP.md`
- `adapters/audition/APP.md`
- `adapters/blender/APP.md`
- `adapters/excel/APP.md`
- `adapters/houdini/APP.md`
- `adapters/illustrator/APP.md`
- `adapters/indesign/APP.md`
- `adapters/photoshop/APP.md`
- `adapters/powerpoint/APP.md`
- `adapters/premiere/APP.md`
- `adapters/unity/APP.md`
- `adapters/word/APP.md`
## Quick Start
1. At the start of a SoftWire session, run `py -m softwire.cli update` on Windows, or `python3 -m softwire.cli update` on macOS/Linux, once to make sure SoftWire is up to date.
2. Read `adapters/<app>/APP.md` for the app you are about to use.
3. Search `adapters/<app>/docs/api-index.txt` with `rg` for relevant symbols.
4. Prefer `py -m softwire.cli context <app>` on Windows, or `python3 -m softwire.cli context <app>` on macOS/Linux, to inspect the live app state.
5. Prefer `py -m softwire.cli run <app> --stdin` on Windows, or `python3 -m softwire.cli run <app> --stdin` on macOS/Linux, for one-off scripts.
## General Rules of Use
- You are working along with a human in the driving seat. Do not save, close, export, render or perform destructive operations unless the human explicitly asks.
- Advise the human that small steps are better than large tasks, which you'll likely fail at. Keep collaboration scope manageable.
- Bound scripts carefully to avoid crashing the host: keep scripts small and targeted.
- All bridge scripts run from workspace root; accepts code through argv, `--stdin`, or `--file`; return JSON on stdout for success or failure.
- Be skeptical of your pretraining: introspect the running app and consult vendor documentation rather than trying to invent operations.
- SoftWire was developed and tested against specific app and OS versions. One could expect local quirks, version mismatches and blocked automation paths. You need to understand the bridge architecture and make small, local compatibility fixes or scaffolds when needed, so the adapter works in the user's actual environment (without rewriting the full project). Make these small and robust, so that they work between sessions.
- Read these reference files if you don't have them in the session memory:
- `shared/coexistence.md`
- `shared/bridge-contract.md`
- `docs/setup.md`
- `docs/known-issues.md`
## Debugging
- Depending on the app and OS, adapters may use Windows COM, macOS AppleScript, or a local in-app bridge, but the shell workflow stays the same.
- On Windows, `py -m softwire.cli ...` is the reliable launcher; on macOS/Linux, use `python3 -m softwire.cli ...`.
- If those are unavailable, use the Python executable that installed SoftWire: `<python> -m softwire.cli ...`.
- Use `py -m softwire.cli where` on Windows, or `python3 -m softwire.cli where` on macOS/Linux, for launcher and install diagnostics.
- If a Windows app is blocked by a modal, use `py -m softwire.cli modal <app>` to inspect likely dialog windows and `py -m softwire.cli modal <app> --dismiss` to attempt a bounded cancel-style dismissal outside the app scripting runtime.
- Use bare `softwire` only as a convenience command when PATH propagation is known to be working.
tools/__init__.py
+1 -1
View File
@@ -1 +1 @@
"""Maintenance tools packaged with SoftWire."""
"""Maintenance tools packaged with Flue."""