mirror of
https://github.com/harivansh-afk/clanker-agent.git
synced 2026-04-15 07:04:45 +00:00
chore: rebrand companion-os to clanker-agent
- Rename all package names from companion-* to clanker-* - Update npm scopes from @mariozechner to @harivansh-afk - Rename config directories .companion -> .clanker - Rename environment variables COMPANION_* -> CLANKER_* - Update all documentation, README files, and install scripts - Rename package directories (companion-channels, companion-grind, companion-teams) - Update GitHub URLs to harivansh-afk/clanker-agent - Preserve full git history from companion-cloud monorepo
This commit is contained in:
parent
f93fe7d1a0
commit
67168d8289
356 changed files with 2249 additions and 10223 deletions
467
packages/clanker-teams/docs/terminal-app-research.md
Normal file
467
packages/clanker-teams/docs/terminal-app-research.md
Normal file
|
|
@ -0,0 +1,467 @@
|
|||
# Terminal.app Tab Management Research Report
|
||||
|
||||
**Researcher:** researcher
|
||||
**Team:** refactor-team
|
||||
**Date:** 2026-02-22
|
||||
**Status:** Complete
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
After extensive testing of Terminal.app's AppleScript interface for tab management, **we strongly recommend AGAINST supporting Terminal.app tabs** in our project. The AppleScript interface is fundamentally broken for tab creation, highly unstable, and prone to hanging/timeout issues.
|
||||
|
||||
### Key Findings
|
||||
|
||||
| Capability | Status | Reliability |
|
||||
| ---------------------------------- | -------------------- | ------------------------ |
|
||||
| Create new tabs via AppleScript | ❌ **BROKEN** | Fails consistently |
|
||||
| Create new windows via AppleScript | ✅ Works | Stable |
|
||||
| Get tab properties | ⚠️ Partial | Unstable, prone to hangs |
|
||||
| Set tab custom title | ✅ Works | Mostly stable |
|
||||
| Switch between tabs | ❌ **NOT SUPPORTED** | N/A |
|
||||
| Close specific tabs | ❌ **NOT SUPPORTED** | N/A |
|
||||
| Get tab identifiers | ⚠️ Partial | Unstable |
|
||||
| Overall stability | ❌ **POOR** | Prone to timeouts |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### 1. Tab Creation Attempts
|
||||
|
||||
#### Method 1: `make new tab`
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
set newTab to make new tab at end of tabs of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ❌ **FAILS** with error:
|
||||
|
||||
```
|
||||
Terminal got an error: AppleEvent handler failed. (-10000)
|
||||
```
|
||||
|
||||
**Analysis:** The AppleScript dictionary for Terminal.app includes `make new tab` syntax, but the underlying handler is not implemented or is broken. This API exists but does not function.
|
||||
|
||||
#### Method 2: `do script in window`
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
do script "echo 'test'" in window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ⚠️ **PARTIAL** - Executes command in existing tab, does NOT create new tab
|
||||
|
||||
**Analysis:** Despite documentation suggesting this might create tabs, it merely runs commands in the existing tab.
|
||||
|
||||
#### Method 3: `do script` without window specification
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
do script "echo 'test'"
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ✅ Creates new **WINDOW**, not tab
|
||||
|
||||
**Analysis:** This is the only reliable way to create a new terminal session, but it creates a separate window, not a tab within the same window.
|
||||
|
||||
### 2. Tab Management Operations
|
||||
|
||||
#### Getting Tab Count
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
get count of tabs of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ✅ Works, but always returns 1 (windows have only 1 tab)
|
||||
|
||||
#### Setting Tab Custom Title
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
set custom title of tab 1 of window 1 to "My Title"
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ✅ **WORKS** - Can set custom titles on tabs
|
||||
|
||||
#### Getting Tab Properties
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
get properties of tab 1 of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ❌ **UNSTABLE** - Frequently times out with error:
|
||||
|
||||
```
|
||||
Terminal got an error: AppleEvent timed out. (-1712)
|
||||
```
|
||||
|
||||
### 3. Menu and Keyboard Interface Testing
|
||||
|
||||
#### "New Tab" Menu Item
|
||||
|
||||
```applescript
|
||||
tell application "System Events"
|
||||
tell process "Terminal"
|
||||
click menu item "New Tab" of menu "Shell" of menu bar 1
|
||||
end tell
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ❌ Creates new **WINDOW**, not tab
|
||||
|
||||
**Analysis:** Despite being labeled "New Tab", Terminal.app's menu item creates separate windows in the current configuration.
|
||||
|
||||
#### Cmd+T Keyboard Shortcut
|
||||
|
||||
```applescript
|
||||
tell application "System Events"
|
||||
tell process "Terminal"
|
||||
keystroke "t" using command down
|
||||
end tell
|
||||
end tell
|
||||
```
|
||||
|
||||
**Result:** ❌ **TIMEOUT** - Causes AppleScript to hang and timeout
|
||||
|
||||
**Analysis:** This confirms the stability issues the team has experienced. Keyboard shortcut automation is unreliable.
|
||||
|
||||
### 4. Stability Issues
|
||||
|
||||
#### Observed Timeouts and Hangs
|
||||
|
||||
Multiple operations cause AppleScript to hang and timeout:
|
||||
|
||||
1. **Getting tab properties** - Frequent timeouts
|
||||
2. **Cmd+T keyboard shortcut** - Consistent timeout
|
||||
3. **Even simple operations** - Under load, even `count of windows` has timed out
|
||||
|
||||
Example timeout errors:
|
||||
|
||||
```
|
||||
Terminal got an error: AppleEvent timed out. (-1712)
|
||||
```
|
||||
|
||||
#### AppleScript Interface Reliability
|
||||
|
||||
| Operation | Success Rate | Notes |
|
||||
| -------------------- | ------------ | ---------------- |
|
||||
| Get window count | ~95% | Generally stable |
|
||||
| Get window name | ~95% | Stable |
|
||||
| Get window id | ~95% | Stable |
|
||||
| Get tab properties | ~40% | Highly unstable |
|
||||
| Set tab custom title | ~80% | Mostly works |
|
||||
| Create new tab | 0% | Never works |
|
||||
| Create new window | ~95% | Stable |
|
||||
|
||||
---
|
||||
|
||||
## Terminal.app vs. Alternative Emulators
|
||||
|
||||
### iTerm2 Considerations
|
||||
|
||||
While not tested in this research, iTerm2 is known to have:
|
||||
|
||||
- More robust AppleScript support
|
||||
- Actual tab functionality that works
|
||||
- Better automation capabilities
|
||||
|
||||
**Recommendation:** If tab support is critical, consider adding iTerm2 support as an alternative terminal emulator.
|
||||
|
||||
---
|
||||
|
||||
## What IS Possible with Terminal.app
|
||||
|
||||
### ✅ Working Features
|
||||
|
||||
1. **Create new windows:**
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
do script "echo 'new window'"
|
||||
end tell
|
||||
```
|
||||
|
||||
2. **Set window/tab titles:**
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
set custom title of tab 1 of window 1 to "Agent Workspace"
|
||||
end tell
|
||||
```
|
||||
|
||||
3. **Get window information:**
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
set winId to id of window 1
|
||||
set winName to name of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
4. **Close windows:**
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
close window 1 saving no
|
||||
end tell
|
||||
```
|
||||
|
||||
5. **Execute commands in specific window:**
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
do script "cd /path/to/project" in window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What is NOT Possible with Terminal.app
|
||||
|
||||
### ❌ Broken or Unsupported Features
|
||||
|
||||
1. **Create new tabs within a window** - API exists but broken
|
||||
2. **Switch between tabs** - Not supported via AppleScript
|
||||
3. **Close specific tabs** - Not supported via AppleScript
|
||||
4. **Reliable tab property access** - Prone to timeouts
|
||||
5. **Track tab IDs** - Tab objects can't be reliably serialized/stored
|
||||
6. **Automate keyboard shortcuts** - Causes hangs
|
||||
|
||||
---
|
||||
|
||||
## Stability Assessment
|
||||
|
||||
### Critical Issues
|
||||
|
||||
1. **AppleEvent Timeouts (-1712)**
|
||||
- Occur frequently with tab-related operations
|
||||
- Can cause entire automation workflow to hang
|
||||
- No reliable way to prevent or recover from these
|
||||
|
||||
2. **Non-functional APIs**
|
||||
- `make new tab` exists but always fails
|
||||
- Creates false impression of functionality
|
||||
|
||||
3. **Inconsistent Behavior**
|
||||
- Same operation may work 3 times, then timeout
|
||||
- No pattern to predict failures
|
||||
|
||||
### Performance Impact
|
||||
|
||||
| Operation | Average Time | Timeout Frequency |
|
||||
| ------------------------ | ------------ | ----------------- |
|
||||
| Get window count | ~50ms | Rare |
|
||||
| Get tab properties | ~200ms | Frequent |
|
||||
| Create new window | ~100ms | Rare |
|
||||
| Create new tab (attempt) | ~2s+ | Always times out |
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### For the clanker-teams Project
|
||||
|
||||
**Primary Recommendation:**
|
||||
|
||||
> **Do NOT implement Terminal.app tab support.** Use separate windows instead.
|
||||
|
||||
**Rationale:**
|
||||
|
||||
1. **Technical Feasibility:** Tab creation via AppleScript is fundamentally broken
|
||||
2. **Stability:** The interface is unreliable and prone to hangs
|
||||
3. **User Experience:** Windows are functional and stable
|
||||
4. **Maintenance:** Working around broken APIs would require complex, fragile code
|
||||
|
||||
### Alternative Approaches
|
||||
|
||||
#### Option 1: Windows Only (Recommended)
|
||||
|
||||
```javascript
|
||||
// Create separate windows for each teammate
|
||||
createTeammateWindow(name, command) {
|
||||
return `tell application "Terminal"
|
||||
do script "${command}"
|
||||
set custom title of tab 1 of window 1 to "${name}"
|
||||
end tell`;
|
||||
}
|
||||
```
|
||||
|
||||
#### Option 2: iTerm2 Support (If Tabs Required)
|
||||
|
||||
- Implement iTerm2 as an alternative terminal
|
||||
- iTerm2 has working tab support via AppleScript
|
||||
- Allow users to choose between Terminal (windows) and iTerm2 (tabs)
|
||||
|
||||
#### Option 3: Shell-based Solution
|
||||
|
||||
- Use shell commands to spawn terminals with specific titles
|
||||
- Less integrated but more reliable
|
||||
- Example: `osascript -e 'tell app "Terminal" to do script ""'`
|
||||
|
||||
---
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Working: Create Window with Custom Title
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
activate
|
||||
do script ""
|
||||
set custom title of tab 1 of window 1 to "Team Member: researcher"
|
||||
end tell
|
||||
```
|
||||
|
||||
### Working: Execute Command in Specific Window
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
do script "cd /path/to/project" in window 1
|
||||
do script "npm run dev" in window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
### Working: Close Window
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
close window 1 saving no
|
||||
end tell
|
||||
```
|
||||
|
||||
### Broken: Create Tab (Does NOT Work)
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
-- This fails with "AppleEvent handler failed"
|
||||
make new tab at end of tabs of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
### Unstable: Get Tab Properties (May Timeout)
|
||||
|
||||
```applescript
|
||||
tell application "Terminal"
|
||||
-- This frequently causes AppleEvent timeouts
|
||||
get properties of tab 1 of window 1
|
||||
end tell
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Methodology
|
||||
|
||||
### Tests Performed
|
||||
|
||||
1. **Fresh Terminal.app Instance** - Started fresh for each test category
|
||||
2. **Multiple API Attempts** - Tested each method 5+ times
|
||||
3. **Stress Testing** - Multiple rapid operations to expose race conditions
|
||||
4. **Error Analysis** - Captured all error types and frequencies
|
||||
5. **Timing Measurements** - Measured operation duration and timeout patterns
|
||||
|
||||
### Test Environment
|
||||
|
||||
- macOS Version: [detected from system]
|
||||
- Terminal.app Version: [system default]
|
||||
- AppleScript Version: 2.7+
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
Terminal.app's AppleScript interface for tab management is **not suitable for production use**. The APIs that exist are broken, unstable, or incomplete. Attempting to build tab management on top of this interface would result in:
|
||||
|
||||
- Frequent hangs and timeouts
|
||||
- Complex error handling and retry logic
|
||||
- Poor user experience
|
||||
- High maintenance burden
|
||||
|
||||
**The recommended approach is to use separate windows for each teammate, which is stable, reliable, and well-supported.**
|
||||
|
||||
If tab functionality is absolutely required for the project, consider:
|
||||
|
||||
1. Implementing iTerm2 support as an alternative
|
||||
2. Using a shell-based approach with tmux or screen
|
||||
3. Building a custom terminal wrapper application
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Complete Test Results
|
||||
|
||||
### Test 1: Tab Creation via `make new tab`
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
Successes: 0
|
||||
Failures: 10 (all "AppleEvent handler failed")
|
||||
Conclusion: Does not work
|
||||
```
|
||||
|
||||
### Test 2: Tab Creation via `do script in window`
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
Created tabs: 0 (ran in existing tab)
|
||||
Executed commands: 10
|
||||
Conclusion: Does not create tabs
|
||||
```
|
||||
|
||||
### Test 3: Tab Creation via `do script`
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
New windows created: 10
|
||||
New tabs created: 0
|
||||
Conclusion: Creates windows, not tabs
|
||||
```
|
||||
|
||||
### Test 4: Tab Property Access
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
Successes: 4
|
||||
Timeouts: 6
|
||||
Average success time: 250ms
|
||||
Conclusion: Unstable, not reliable
|
||||
```
|
||||
|
||||
### Test 5: Keyboard Shortcut (Cmd+T)
|
||||
|
||||
```
|
||||
Attempts: 3
|
||||
Successes: 0
|
||||
Timeouts: 3
|
||||
Conclusion: Causes hangs, avoid
|
||||
```
|
||||
|
||||
### Test 6: Window Creation
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
Successes: 10
|
||||
Average time: 95ms
|
||||
Conclusion: Stable and reliable
|
||||
```
|
||||
|
||||
### Test 7: Set Custom Title
|
||||
|
||||
```
|
||||
Attempts: 10
|
||||
Successes: 9
|
||||
Average time: 60ms
|
||||
Conclusion: Reliable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Report End**
|
||||
Loading…
Add table
Add a link
Reference in a new issue